Bump Azure.Identity from 1.17.1 to 1.21.0

--- updated-dependencies: - dependency-name: Azure.Identity dependency-version: 1.21.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <support@github.com>
.NET: Features/3768-devui-aspire-integration (#3771 )
2026-06-16 21:04:09 +08:00 · 2026-04-20 11:34:06 +00:00 · 2026-04-20 11:12:54 +00:00 · 2026-04-20 08:29:40 +00:00 · 2026-04-20 03:30:54 +00:00 · 2026-04-17 20:15:27 +00:00
1300 changed files with 65404 additions and 35962 deletions
@@ -21,6 +21,7 @@ ignorePatterns:
  - pattern: "http://host.docker.internal"
  - pattern: "https://openai.github.io/openai-agents-js/openai/agents/classes/"
  - pattern: "https:\/\/dotnet.microsoft.com\/download"
+  - pattern: "https://github.com/Rel1cx/eslint-react"
 # excludedDirs:
  # Folders which include links to localhost, since it's not ignored with regular expressions
 baseUrl: https://github.com/microsoft/agent-framework/
@@ -47,7 +47,7 @@ body:
    attributes:
      label: Package Versions
      description: List the agent-framework-* packages and versions you are using
-      placeholder: "e.g., agent-framework-core: 1.0.0, agent-framework-azure-ai: 1.0.0"
+      placeholder: "e.g., agent-framework-core: 1.0.0, agent-framework-foundry: 1.0.0"
    validations:
      required: true

@@ -34,7 +34,7 @@ runs:

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

    - name: Azure CLI Login
      uses: azure/login@v2
@@ -82,7 +82,7 @@ jobs:
              .github
              dotnet
              python
-              workflow-samples
+              declarative-agents

      - name: Setup dotnet
        uses: actions/setup-dotnet@v5.2.0
@@ -152,7 +152,7 @@ jobs:
              .github
              dotnet
              python
-              workflow-samples
+              declarative-agents

      # Start Cosmos DB Emulator for all integration tests and only for unit tests when CosmosDB changes happened)
      - name: Start Azure Cosmos DB Emulator
@@ -38,7 +38,7 @@ jobs:
            .github
            dotnet
            python
-            workflow-samples
+            declarative-agents

      - name: Start Azure Cosmos DB Emulator
        if: runner.os == 'Windows'
@@ -0,0 +1,137 @@
+#
+# Runs the .NET sample verification tool, which builds and executes sample projects
+# and verifies their output using deterministic checks and AI-powered verification.
+#
+# Results are displayed as a GitHub Job Summary and the CSV report is uploaded as an artifact.
+#
+
+name: dotnet-verify-samples
+
+on:
+  workflow_dispatch:
+    inputs:
+      category:
+        description: "Sample category to run (blank for all)"
+        required: false
+        type: choice
+        options:
+          - ""
+          - "01-get-started"
+          - "02-agents"
+          - "03-workflows"
+      parallelism:
+        description: "Max parallel sample runs"
+        required: false
+        default: "8"
+        type: string
+  schedule:
+    - cron: "0 6 * * 1-5" # Weekdays at 6:00 UTC
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  verify-samples:
+    runs-on: ubuntu-latest
+    environment: 'integration'
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+          sparse-checkout: |
+            .
+            .github
+            dotnet
+            python
+            declarative-agents
+
+      - name: Setup dotnet
+        uses: actions/setup-dotnet@v5.2.0
+        with:
+          global-json-file: ${{ github.workspace }}/dotnet/global.json
+
+      - name: Azure CLI Login
+        if: github.event_name != 'pull_request'
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Generate filtered solution
+        shell: pwsh
+        run: |
+          ./dotnet/eng/scripts/New-FilteredSolution.ps1 `
+            -Solution dotnet/agent-framework-dotnet.slnx `
+            -TargetFramework net10.0 `
+            -Configuration Debug `
+            -OutputPath dotnet/filtered.slnx `
+            -Verbose
+
+      - name: Build solution
+        shell: bash
+        run: dotnet build dotnet/filtered.slnx -f net10.0 --warnaserror
+
+      - name: Run verify-samples
+        id: verify
+        working-directory: dotnet
+        shell: bash
+        run: |
+          CATEGORY_ARG=""
+          if [ -n "$CATEGORY_INPUT" ]; then
+            CATEGORY_ARG="--category $CATEGORY_INPUT"
+          fi
+
+          dotnet run --project eng/verify-samples -- \
+            $CATEGORY_ARG \
+            --parallel "$PARALLELISM" \
+            --md results.md \
+            --csv results.csv \
+            --log results.log
+        env:
+          CATEGORY_INPUT: ${{ github.event.inputs.category || '' }}
+          PARALLELISM: ${{ github.event.inputs.parallelism || '8' }}
+          # OpenAI Models
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_CHAT_MODEL_NAME: ${{ vars.OPENAI_CHAT_MODEL_NAME }}
+          OPENAI_REASONING_MODEL_NAME: ${{ vars.OPENAI_REASONING_MODEL_NAME }}
+          # Azure OpenAI Models
+          AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
+          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
+          AZURE_OPENAI_ENDPOINT: ${{ vars.AZURE_OPENAI_ENDPOINT }}
+          # Azure AI Foundry
+          AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
+          AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
+          AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}
+
+      - name: Write Job Summary
+        if: always()
+        working-directory: dotnet
+        shell: bash
+        run: |
+          if [ -f results.md ]; then
+            cat results.md >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "⚠️ No results.md generated — verify-samples may have failed to start." >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - name: Upload results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: verify-samples-results
+          path: |
+            dotnet/results.csv
+            dotnet/results.log
+          if-no-files-found: warn
+
+      - name: Fail if samples failed
+        if: always() && steps.verify.outcome == 'failure'
+        shell: bash
+        run: exit 1
@@ -34,14 +34,14 @@ from dataclasses import dataclass
 #   (e.g., "packages/core/agent_framework/observability.py")
 # =============================================================================
 ENFORCED_TARGETS: set[str] = {
-    # Packages
-    "packages.azure-ai.agent_framework_azure_ai",
-    "packages.core.agent_framework",
-    "packages.core.agent_framework._workflows",
-    "packages.purview.agent_framework_purview",
+    # Packages (sorted alphabetically)
    "packages.anthropic.agent_framework_anthropic",
    "packages.azure-ai-search.agent_framework_azure_ai_search",
+    "packages.core.agent_framework",
+    "packages.core.agent_framework._workflows",
+    "packages.foundry.agent_framework_foundry",
    "packages.openai.agent_framework_openai",
+    "packages.purview.agent_framework_purview",
    # 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
@@ -60,8 +60,8 @@ jobs:
    environment: integration
    timeout-minutes: 60
    env:
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
@@ -95,10 +95,10 @@ jobs:
    environment: integration
    timeout-minutes: 60
    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_CHAT_COMPLETION_MODEL: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_CHAT_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_EMBEDDING_MODEL: ${{ vars.AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME }}
      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
    defaults:
      run:
@@ -126,14 +126,12 @@ jobs:
          packages/openai/tests/openai/test_openai_chat_completion_client_azure.py
          packages/openai/tests/openai/test_openai_chat_client_azure.py
          packages/openai/tests/openai/test_openai_embedding_client_azure.py
-          packages/azure-ai/tests/azure_openai
-          --ignore=packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
          -m integration
          -n logical --dist worksteal
          --timeout=120 --session-timeout=900 --timeout_method thread
          --retries 2 --retry-delay 5

-  # Misc integration tests (Anthropic, Ollama, MCP)
+  # Misc integration tests (Anthropic, Hyperlight, Ollama, MCP)
  python-tests-misc-integration:
    name: Python Integration Tests - Misc
    runs-on: ubuntu-latest
@@ -141,7 +139,7 @@ jobs:
    timeout-minutes: 60
    env:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
+      ANTHROPIC_CHAT_MODEL: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
    defaults:
      run:
@@ -164,16 +162,17 @@ jobs:
          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)
+      - name: Test with pytest (Anthropic, Hyperlight, Ollama, MCP integration)
        run: >
          uv run pytest --import-mode=importlib
          packages/anthropic/tests
+          packages/hyperlight/tests
          packages/ollama/tests
          packages/core/tests/core/test_mcp.py
          -m integration
          -n logical --dist worksteal
          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
+          --retries 2 --retry-delay 30
      - name: Stop local MCP server
        if: always()
        shell: bash
@@ -203,14 +202,15 @@ jobs:
    timeout-minutes: 60
    env:
      UV_PYTHON: "3.11"
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
      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 }}
+      AZURE_OPENAI_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_CHAT_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
      FUNCTIONS_WORKER_RUNTIME: "python"
@@ -257,12 +257,14 @@ jobs:
    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 }}
+      FOUNDRY_MODELS_ENDPOINT: ${{ vars.FOUNDRY_MODELS_ENDPOINT || '' }}
+      FOUNDRY_MODELS_API_KEY: ${{ secrets.FOUNDRY_MODELS_API_KEY || '' }}
+      FOUNDRY_EMBEDDING_MODEL: ${{ vars.FOUNDRY_EMBEDDING_MODEL || '' }}
+      FOUNDRY_IMAGE_EMBEDDING_MODEL: ${{ vars.FOUNDRY_IMAGE_EMBEDDING_MODEL || '' }}
      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
    defaults:
      run:
@@ -288,7 +290,6 @@ jobs:
        timeout-minutes: 15
        run: >
          uv run pytest --import-mode=importlib
-          packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
          packages/foundry/tests
          -m integration
          -n logical --dist worksteal
@@ -37,7 +37,7 @@ jobs:
      azureChanged: ${{ steps.filter.outputs.azure }}
      miscChanged: ${{ steps.filter.outputs.misc }}
      functionsChanged: ${{ steps.filter.outputs.functions }}
-      azureAiChanged: ${{ steps.filter.outputs.azure-ai }}
+      foundryChanged: ${{ steps.filter.outputs.foundry }}
      cosmosChanged: ${{ steps.filter.outputs.cosmos }}
    steps:
      - uses: actions/checkout@v6
@@ -62,11 +62,10 @@ jobs:
            azure:
              - 'python/packages/openai/**'
              - 'python/packages/core/agent_framework/azure/**'
-              - 'python/packages/azure-ai/agent_framework_azure_ai/_deprecated_azure_openai.py'
-              - 'python/packages/azure-ai/tests/azure_openai/**'
-              - 'python/samples/**/providers/azure/openai_chat_completion_client_azure*.py'
+              - 'python/samples/**/providers/azure/**'
            misc:
              - 'python/packages/anthropic/**'
+              - 'python/packages/hyperlight/**'
              - 'python/packages/ollama/**'
              - 'python/packages/core/agent_framework/_mcp.py'
              - 'python/packages/core/tests/core/test_mcp.py'
@@ -77,10 +76,10 @@ jobs:
            functions:
              - 'python/packages/azurefunctions/**'
              - 'python/packages/durabletask/**'
-            azure-ai:
-              - 'python/packages/azure-ai/**'
+            foundry:
              - 'python/packages/foundry/**'
              - 'python/samples/**/providers/foundry/**'
+              - 'python/samples/02-agents/embeddings/foundry_embeddings.py'
            cosmos:
              - 'python/packages/azure-cosmos/**'
      # run only if 'python' files were changed
@@ -117,12 +116,13 @@ jobs:
          -m "not integration"
          --timeout=120 --session-timeout=900 --timeout_method thread
          --retries 2 --retry-delay 5
+          --junitxml=pytest.xml
        working-directory: ./python
      - name: Surface failing tests
        if: always()
        uses: pmeier/pytest-results-action@v0.7.2
        with:
-          path: ./python/**.xml
+          path: ./python/pytest.xml
          summary: true
          display-options: fEX
          fail-on-empty: false
@@ -141,8 +141,8 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    env:
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
@@ -165,6 +165,7 @@ jobs:
          -n logical --dist worksteal
          --timeout=120 --session-timeout=900 --timeout_method thread
          --retries 2 --retry-delay 5
+          --junitxml=pytest.xml
        working-directory: ./python
      - name: Test OpenAI samples
        timeout-minutes: 10
@@ -175,7 +176,7 @@ jobs:
        if: always()
        uses: pmeier/pytest-results-action@v0.7.2
        with:
-          path: ./python/**.xml
+          path: ./python/pytest.xml
          summary: true
          display-options: fEX
          fail-on-empty: false
@@ -194,10 +195,10 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    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_CHAT_COMPLETION_MODEL: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_CHAT_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_EMBEDDING_MODEL: ${{ vars.AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME }}
      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
    defaults:
      run:
@@ -223,12 +224,11 @@ jobs:
          packages/openai/tests/openai/test_openai_chat_completion_client_azure.py
          packages/openai/tests/openai/test_openai_chat_client_azure.py
          packages/openai/tests/openai/test_openai_embedding_client_azure.py
-          packages/azure-ai/tests/azure_openai
-          --ignore=packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
          -m integration
          -n logical --dist worksteal
          --timeout=120 --session-timeout=900 --timeout_method thread
          --retries 2 --retry-delay 5
+          --junitxml=pytest.xml
        working-directory: ./python
      - name: Test Azure samples
        timeout-minutes: 10
@@ -239,7 +239,7 @@ jobs:
        if: always()
        uses: pmeier/pytest-results-action@v0.7.2
        with:
-          path: ./python/**.xml
+          path: ./python/pytest.xml
          summary: true
          display-options: fEX
          fail-on-empty: false
@@ -259,7 +259,7 @@ jobs:
    environment: integration
    env:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
+      ANTHROPIC_CHAT_MODEL: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
    defaults:
      run:
@@ -279,16 +279,18 @@ jobs:
          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)
+      - name: Test with pytest (Anthropic, Hyperlight, Ollama, MCP integration)
        run: >
          uv run pytest --import-mode=importlib
          packages/anthropic/tests
+          packages/hyperlight/tests
          packages/ollama/tests
          packages/core/tests/core/test_mcp.py
          -m integration
          -n logical --dist worksteal
          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
+          --retries 2 --retry-delay 30
+          --junitxml=pytest.xml
        working-directory: ./python
      - name: Stop local MCP server
        if: always()
@@ -314,7 +316,7 @@ jobs:
        if: always()
        uses: pmeier/pytest-results-action@v0.7.2
        with:
-          path: ./python/**.xml
+          path: ./python/pytest.xml
          summary: true
          display-options: fEX
          fail-on-empty: false
@@ -334,14 +336,15 @@ jobs:
    environment: integration
    env:
      UV_PYTHON: "3.11"
-      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
      OPENAI_EMBEDDING_MODEL: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
      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 }}
+      AZURE_OPENAI_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_CHAT_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL }}
      FUNCTIONS_WORKER_RUNTIME: "python"
@@ -378,12 +381,13 @@ jobs:
          -x
          --timeout=360 --session-timeout=900 --timeout_method thread
          --retries 2 --retry-delay 5
+          --junitxml=pytest.xml
        working-directory: ./python
      - name: Surface failing tests
        if: always()
        uses: pmeier/pytest-results-action@v0.7.2
        with:
-          path: ./python/**.xml
+          path: ./python/pytest.xml
          summary: true
          display-options: fEX
          fail-on-empty: false
@@ -396,13 +400,11 @@ jobs:
      github.event_name != 'pull_request' &&
      needs.paths-filter.outputs.pythonChanges == 'true' &&
      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.azureAiChanged == 'true' ||
+       needs.paths-filter.outputs.foundryChanged == 'true' ||
       needs.paths-filter.outputs.coreChanged == 'true')
    runs-on: ubuntu-latest
    environment: integration
    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 }}
@@ -430,23 +432,18 @@ jobs:
        timeout-minutes: 15
        run: >
          uv run pytest --import-mode=importlib
-          packages/azure-ai/tests/azure_openai/test_azure_responses_client_foundry.py
          packages/foundry/tests
          -m integration
          -n logical --dist worksteal
          --timeout=120 --session-timeout=900 --timeout_method thread
          --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Test Azure AI samples
-        timeout-minutes: 10
-        if: env.RUN_SAMPLES_TESTS == 'true'
-        run: uv run pytest tests/samples/ -m "azure-ai"
+          --junitxml=pytest.xml
        working-directory: ./python
      - name: Surface failing tests
        if: always()
        uses: pmeier/pytest-results-action@v0.7.2
        with:
-          path: ./python/**.xml
+          path: ./python/pytest.xml
          summary: true
          display-options: fEX
          fail-on-empty: false
@@ -500,13 +497,13 @@ jobs:
          echo "Cosmos DB emulator did not become ready in time." >&2
          exit 1
      - name: Test with pytest (Cosmos integration)
-        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5 --junitxml=pytest.xml
        working-directory: ./python
      - name: Surface failing tests
        if: always()
        uses: pmeier/pytest-results-action@v0.7.2
        with:
-          path: ./python/**.xml
+          path: ./python/pytest.xml
          summary: true
          display-options: fEX
          fail-on-empty: false
@@ -23,10 +23,8 @@ jobs:
    environment: integration
    env:
      # Required configuration for get-started samples
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT || vars.AZURE_AI_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
    defaults:
      run:
        working-directory: python
@@ -43,10 +41,8 @@ jobs:

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

      - name: Run sample validation
        run: |
@@ -64,18 +60,19 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # Foundry configuration
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT || vars.AZURE_AI_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
      # Azure OpenAI configuration
      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
+      AZURE_OPENAI_MODEL: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_CHAT_MODEL: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_EMBEDDING_MODEL: ${{ vars.AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME || vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
      # OpenAI configuration
      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
      # GitHub MCP
      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
@@ -97,15 +94,16 @@ jobs:

      - name: Create .env for samples
        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
+          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
+          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env
          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME=$AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME" >> .env
+          echo "AZURE_OPENAI_MODEL=$AZURE_OPENAI_MODEL" >> .env
+          echo "AZURE_OPENAI_CHAT_COMPLETION_MODEL=$AZURE_OPENAI_CHAT_COMPLETION_MODEL" >> .env
+          echo "AZURE_OPENAI_CHAT_MODEL=$AZURE_OPENAI_CHAT_MODEL" >> .env
+          echo "AZURE_OPENAI_EMBEDDING_MODEL=$AZURE_OPENAI_EMBEDDING_MODEL" >> .env
          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
-          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
-          echo "OPENAI_RESPONSES_MODEL_ID=$OPENAI_RESPONSES_MODEL_ID" >> .env
+          echo "OPENAI_CHAT_COMPLETION_MODEL=$OPENAI_CHAT_COMPLETION_MODEL" >> .env
+          echo "OPENAI_CHAT_MODEL=$OPENAI_CHAT_MODEL" >> .env
          echo "GITHUB_PAT=$GITHUB_PAT" >> .env

      - name: Run sample validation
@@ -125,8 +123,9 @@ jobs:
    environment: integration
    env:
      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_MODEL: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
    defaults:
      run:
        working-directory: python
@@ -144,8 +143,9 @@ jobs:
      - name: Create .env for samples
        run: |
          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
-          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
-          echo "OPENAI_RESPONSES_MODEL_ID=$OPENAI_RESPONSES_MODEL_ID" >> .env
+          echo "OPENAI_MODEL=$OPENAI_MODEL" >> .env
+          echo "OPENAI_CHAT_COMPLETION_MODEL=$OPENAI_CHAT_COMPLETION_MODEL" >> .env
+          echo "OPENAI_CHAT_MODEL=$OPENAI_CHAT_MODEL" >> .env

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

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

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

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

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

  validate-02-agents-anthropic:
@@ -285,7 +203,7 @@ jobs:
    environment: integration
    env:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
+      ANTHROPIC_CHAT_MODEL: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
    defaults:
      run:
        working-directory: python
@@ -303,7 +221,7 @@ jobs:
      - name: Create .env for samples
        run: |
          echo "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" >> .env
-          echo "ANTHROPIC_CHAT_MODEL_ID=$ANTHROPIC_CHAT_MODEL_ID" >> .env
+          echo "ANTHROPIC_CHAT_MODEL=$ANTHROPIC_CHAT_MODEL" >> .env

      - name: Run sample validation
        run: |
@@ -351,7 +269,7 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    env:
-      BEDROCK_CHAT_MODEL_ID: ${{ vars.BEDROCK__CHATMODELID }}
+      BEDROCK_CHAT_MODEL: ${{ vars.BEDROCK__CHATMODELID }}
    defaults:
      run:
        working-directory: python
@@ -409,11 +327,16 @@ jobs:
          name: validation-report-02-agents-ollama
          path: python/samples/sample_validation/reports/

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

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

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

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

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

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

      - name: Create .env for samples
        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
+          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
+          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env
          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
+          echo "AZURE_OPENAI_MODEL=$AZURE_OPENAI_MODEL" >> .env
          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
-          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
-          echo "OPENAI_RESPONSES_MODEL_ID=$OPENAI_RESPONSES_MODEL_ID" >> .env
+          echo "OPENAI_CHAT_COMPLETION_MODEL=$OPENAI_CHAT_COMPLETION_MODEL" >> .env
+          echo "OPENAI_CHAT_MODEL=$OPENAI_CHAT_MODEL" >> .env

      - name: Run sample validation
        run: |
@@ -694,18 +610,20 @@ jobs:
    runs-on: ubuntu-latest
    environment: integration
    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
+      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT || vars.AZURE_AI_PROJECT_ENDPOINT }}
+      FOUNDRY_MODEL: ${{ vars.FOUNDRY_MODEL || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # Azure OpenAI configuration for AF
      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # OpenAI configuration
+      AZURE_OPENAI_MODEL: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME || vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      # Azure OpenAI configuration for SK
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
+      # OpenAI key
      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_CHAT_COMPLETION_MODEL: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_CHAT_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
      OPENAI_MODEL: ${{ vars.OPENAI__RESPONSESMODELID }}
+      # OpenAI configuration for SK
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
      # Copilot Studio
      COPILOTSTUDIOAGENT__ENVIRONMENTID: ${{ secrets.COPILOTSTUDIOAGENT__ENVIRONMENTID }}
      COPILOTSTUDIOAGENT__SCHEMANAME: ${{ secrets.COPILOTSTUDIOAGENT__SCHEMANAME }}
@@ -727,14 +645,13 @@ jobs:

      - name: Create .env for samples
        run: |
-          echo "AZURE_AI_PROJECT_ENDPOINT=$AZURE_AI_PROJECT_ENDPOINT" >> .env
-          echo "AZURE_AI_MODEL_DEPLOYMENT_NAME=$AZURE_AI_MODEL_DEPLOYMENT_NAME" >> .env
+          echo "FOUNDRY_PROJECT_ENDPOINT=$FOUNDRY_PROJECT_ENDPOINT" >> .env
+          echo "FOUNDRY_MODEL=$FOUNDRY_MODEL" >> .env
          echo "AZURE_OPENAI_ENDPOINT=$AZURE_OPENAI_ENDPOINT" >> .env
-          echo "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=$AZURE_OPENAI_CHAT_DEPLOYMENT_NAME" >> .env
-          echo "AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=$AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME" >> .env
+          echo "AZURE_OPENAI_MODEL=$AZURE_OPENAI_MODEL" >> .env
          echo "OPENAI_API_KEY=$OPENAI_API_KEY" >> .env
-          echo "OPENAI_CHAT_MODEL_ID=$OPENAI_CHAT_MODEL_ID" >> .env
-          echo "OPENAI_RESPONSES_MODEL_ID=$OPENAI_RESPONSES_MODEL_ID" >> .env
+          echo "OPENAI_CHAT_COMPLETION_MODEL=$OPENAI_CHAT_COMPLETION_MODEL" >> .env
+          echo "OPENAI_CHAT_MODEL=$OPENAI_CHAT_MODEL" >> .env
          echo "COPILOTSTUDIOAGENT__ENVIRONMENTID=$COPILOTSTUDIOAGENT__ENVIRONMENTID" >> .env
          echo "COPILOTSTUDIOAGENT__SCHEMANAME=$COPILOTSTUDIOAGENT__SCHEMANAME" >> .env
          echo "COPILOTSTUDIOAGENT__TENANTID=$COPILOTSTUDIOAGENT__TENANTID" >> .env
@@ -759,14 +676,12 @@ jobs:
      - validate-01-get-started
      - validate-02-agents
      - validate-02-agents-openai
-      - validate-02-agents-azure-openai
-      - validate-02-agents-azure-ai
-      - validate-02-agents-azure-ai-agent
+      - validate-02-agents-azure
      - validate-02-agents-anthropic
      - validate-02-agents-github-copilot
      - validate-02-agents-amazon
      - validate-02-agents-ollama
-      - validate-02-agents-foundry-local
+      - validate-02-agents-foundry
      - validate-02-agents-copilotstudio
      - validate-02-agents-custom
      - validate-03-workflows
@@ -40,7 +40,7 @@ jobs:
          UV_CACHE_DIR: /tmp/.uv-cache
      # Unit tests
      - name: Run all tests
-        run: uv run poe test -A
+        run: uv run poe test -A --junitxml=pytest.xml
        working-directory: ./python

      # Surface failing tests
@@ -48,7 +48,7 @@ jobs:
        if: always()
        uses: pmeier/pytest-results-action@v0.7.2
        with:
-          path: ./python/**.xml
+          path: ./python/pytest.xml
          summary: true
          display-options: fEX
          fail-on-empty: false
@@ -47,6 +47,8 @@ htmlcov/
 .cache
 nosetests.xml
 coverage.xml
+pytest.xml
+python-coverage.xml
 *.cover
 *.py,cover
 .hypothesis/
@@ -230,3 +232,7 @@ local.settings.json
 # Database files
 *.db
 python/dotnet-ref
+
+# Generated filtered solution files (created by eng/scripts/New-FilteredSolution.ps1)
+dotnet/filtered-*.slnx
+**/*.lscache
@@ -74,6 +74,37 @@ Contributions must maintain API signature and behavioral compatibility. Contribu
 that include breaking changes will be rejected. Please file an issue to discuss
 your idea or change if you believe that a breaking change is warranted.

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

 We use and recommend the following workflow:
@@ -92,22 +123,30 @@ We use and recommend the following workflow:
     "issue-123" or "githubhandle-issue".
 4. Make and commit your changes to your branch.
 5. Add new tests corresponding to your change, if applicable.
-6. Run the relevant scripts in [the section below](#development-scripts) to ensure that your build is clean and all tests are passing.
+6. Run the relevant scripts in [the section below](#development-setup) to ensure that your build is clean and all tests are passing.
 7. Create a PR against the repository's **main** branch.
   - State in the description what issue or improvement your change is addressing.
   - Verify that all the Continuous Integration checks are passing.
 8. Wait for feedback or approval of your changes from the code maintainers.
 9. When area owners have signed off, and all checks are green, your PR will be merged.

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

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

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

 ### PR - CI Process

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

 # Welcome to Microsoft Agent Framework!

-[![Microsoft Azure AI Foundry Discord](https://dcbadge.limes.pink/api/server/b5zjErwbQM?style=flat)](https://discord.gg/b5zjErwbQM)
+[![Microsoft Foundry Discord](https://dcbadge.limes.pink/api/server/b5zjErwbQM?style=flat)](https://discord.gg/b5zjErwbQM)
 [![MS Learn Documentation](https://img.shields.io/badge/MS%20Learn-Documentation-blue)](https://learn.microsoft.com/en-us/agent-framework/)
 [![PyPI](https://img.shields.io/pypi/v/agent-framework)](https://pypi.org/project/agent-framework/)
 [![NuGet](https://img.shields.io/nuget/v/Microsoft.Agents.AI)](https://www.nuget.org/profiles/MicrosoftAgentFramework/)
@@ -28,7 +28,7 @@ Welcome to Microsoft's comprehensive multi-language framework for building, orch
 Python

 ```bash
-pip install agent-framework --pre
+pip install agent-framework
 # This will install all sub-packages, see `python/packages` for individual packages.
 # It may take a minute on first install on Windows.
 ```
@@ -90,27 +90,27 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 Create a simple Azure Responses Agent that writes a haiku about the Microsoft Agent Framework

 ```python
-# pip install agent-framework --pre
+# pip install agent-framework
 # Use `az login` to authenticate with Azure CLI
 import os
 import asyncio
-from agent_framework.azure import AzureOpenAIResponsesClient
+from agent_framework import Agent
+from agent_framework.foundry import FoundryChatClient
 from azure.identity import AzureCliCredential


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

    print(await agent.run("Write a haiku about Microsoft Agent Framework."))
@@ -120,41 +120,38 @@ if __name__ == "__main__":
 ```

 ### Basic Agent - .NET
+Create a simple Agent, using Microsoft Foundry with token-based auth, that writes a haiku about the Microsoft Agent Framework
+
+```c#
+// dotnet add package Microsoft.Agents.AI.Foundry
+// Use `az login` to authenticate with Azure CLI
+using Azure.AI.Projects;
+using Azure.Identity;
+using System;
+using Azure.AI.Projects;
+using Azure.Identity;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+
+var agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
+    .AsAIAgent(model: deploymentName, name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+
+Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
+```

 Create a simple Agent, using OpenAI Responses, that writes a haiku about the Microsoft Agent Framework

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

 // Replace the <apikey> with your OpenAI API key.
 var agent = new OpenAIClient("<apikey>")
-    .GetResponsesClient("gpt-4o-mini")
-    .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
-
-Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
-```
-
-Create a simple Agent, using Azure OpenAI Responses with token based auth, that writes a haiku about the Microsoft Agent Framework
-
-```c#
-// dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
-// dotnet add package Azure.Identity
-// Use `az login` to authenticate with Azure CLI
-using System.ClientModel.Primitives;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using OpenAI;
-using OpenAI.Responses;
-
-// Replace <resource> and gpt-4o-mini with your Azure OpenAI resource name and deployment name.
-var agent = new OpenAIClient(
-    new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"),
-    new OpenAIClientOptions() { Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1") })
-    .GetResponsesClient("gpt-4o-mini")
-    .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+    .GetResponsesClient()
+    .AsAIAgent(model: "gpt-5.4-mini", name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");

 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```
@@ -163,15 +160,43 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram

 ### Python

- [Getting Started with Agents](./python/samples/01-get-started): progressive tutorial from hello-world to hosting
+- [Getting Started](./python/samples/01-get-started): progressive tutorial from hello-world to hosting
 - [Agent Concepts](./python/samples/02-agents): deep-dive samples by topic (tools, middleware, providers, etc.)
- [Getting Started with Workflows](./python/samples/03-workflows): workflow creation and integration with agents
+- [Workflows](./python/samples/03-workflows): workflow creation and integration with agents
+- [Hosting](./python/samples/04-hosting): A2A, Azure Functions, Durable Task hosting
+- [End-to-End](./python/samples/05-end-to-end): full applications, evaluation, and demos

 ### .NET

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

 ## Contributor Resources

@@ -182,4 +207,9 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram

 ## Important Notes

-If you use the Microsoft Agent Framework to build applications that operate with third-party servers or agents, you do so at your own risk. We recommend reviewing all data being shared with third-party servers or agents and being cognizant of third-party practices for retention and location of data. It is your responsibility to manage whether your data will flow outside of your organization's Azure compliance and geographic boundaries and any related implications.
+> [!IMPORTANT]
+> If you use Microsoft Agent Framework to build applications that operate with any third-party servers, agents, code, or non-Azure Direct models (“Third-Party Systems”), you do so at your own risk. Third-Party Systems are Non-Microsoft Products under the Microsoft Product Terms and are governed by their own third-party license terms. You are responsible for any usage and associated costs.
+>
+>We recommend reviewing all data being shared with and received from Third-Party Systems and being cognizant of third-party practices for handling, sharing, retention and location of data. It is your responsibility to manage whether your data will flow outside of your organization’s Azure compliance and geographic boundaries and any related implications, and that appropriate permissions, boundaries and approvals are provisioned.
+> 
+>You are responsible for carefully reviewing and testing applications you build using Microsoft Agent Framework in the context of your specific use cases, and making all appropriate decisions and customizations. This includes implementing your own responsible AI mitigations such as metaprompt, content filters, or other safety systems, and ensuring your applications meet appropriate quality, reliability, security, and trustworthiness standards. See also: [Transparency FAQ](./TRANSPARENCY_FAQ.md)
@@ -1,3 +1,3 @@
 # Declarative Agents

-This folder contains sample agent definitions that can be run using the declarative agent support, for python see the [declarative agent python sample folder](../python/samples/02-agents/declarative/).
+This folder contains sample agent definitions that can be run using the declarative agent support, for python see the [declarative agent python sample folder](../../python/samples/02-agents/declarative/).
@@ -3,13 +3,13 @@ name: MicrosoftLearnAgent
 description: Microsoft Learn Agent
 instructions: You answer questions by searching the Microsoft Learn content only.
 model:
-    id: =Env.AZURE_FOUNDRY_PROJECT_MODEL_ID
+    id: =Env.FOUNDRY_MODEL
    options:
        temperature: 0.9
        topP: 0.95
    connection:
        kind: remote
-        endpoint: =Env.AZURE_FOUNDRY_PROJECT_ENDPOINT
+        endpoint: =Env.FOUNDRY_PROJECT_ENDPOINT
 tools:
  - kind: mcp
    name: microsoft_learn
@@ -10,8 +10,8 @@ Workflow workflow = DeclarativeWorkflowBuilder.Build("Marketing.yaml", options);
 ```

 These example workflows may be executed by the workflow
-[Samples](../dotnet/samples/03-workflows/Declarative)
+[Samples](../../dotnet/samples/03-workflows/Declarative)
 that are present in this repository.

-> See the [README.md](../dotnet/samples/03-workflows/Declarative/README.md) 
+> See the [README.md](../../dotnet/samples/03-workflows/Declarative/README.md) 
 associated with the samples for configuration details.
@@ -37,7 +37,7 @@ Key changes:
 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`).
+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_CHAT_MODEL_ID` / `OPENAI_CHAT_COMPLETION_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`
@@ -31,8 +31,6 @@ The persistence timing and `FunctionResultContent` trimming behaviors are interr

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

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

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

 ## Considered Options

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

 ## Pros and Cons of the Options

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

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

 - Good, because runs are atomic — chat history is only updated when the full run succeeds, satisfying driver B.
 - Good, because the mental model is simple: one run = one history update, satisfying driver D.
 - Good, because trimming trailing `FunctionResultContent` improves consistency with service storage, partially satisfying driver A.
- Good, because users can opt in to per-service-call persistence for checkpointing/recovery scenarios, satisfying drivers C and E.
 - Bad, because the default persistence timing still differs from the service's behavior (per-run vs. per-service-call), only partially satisfying driver A.
- Bad, because if the process crashes mid-loop, all intermediate progress from the current run is lost, not satisfying driver C by default.
+- Bad, because if the process crashes mid-loop, all intermediate progress from the current run is lost, not satisfying driver C.
+- Bad, because this option alone does not provide a way for users to opt into per-service-call persistence, not satisfying driver E.

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

-Change the default to persist chat history after each individual service call within the FIC loop, matching the AI service's behavior. Trailing `FunctionResultContent` trimming is unnecessary with this approach (it is naturally handled). Provide an opt-in setting for users who want per-run atomicity with trimming.
+Introduce an optional RequirePerServiceCallChatHistoryPersistence setting to persist chat history after each individual service call within the FIC loop, matching the AI service's behavior. Trailing `FunctionResultContent` trimming is unnecessary with this approach (it is naturally handled).

 Settings:
- `PersistChatHistoryAtEndOfRun` = `false` (default)
+- `RequirePerServiceCallChatHistoryPersistence` = `true`

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

 ## Decision Outcome

-Chosen option: **Option 2 — Default to per-service-call persistence**, because it fully satisfies the consistency driver (A), naturally handles `FunctionResultContent` trimming without additional logic, and provides better recoverability for long-running tool-calling loops. Per-run persistence remains available via the `PersistChatHistoryAtEndOfRun` setting for users who prefer atomic run semantics.
+Chosen option: **Option 2: Opt-in per-service-call persistence (via `RequirePerServiceCallChatHistoryPersistence`)**. The existing per-run persistence behavior is retained as-is, requiring no changes from users. Per-service-call persistence is available as an opt-in feature via the `RequirePerServiceCallChatHistoryPersistence` setting. This satisfies drivers B (atomicity) and D (simplicity) for the common case, while fully satisfying driver A (consistency) for users who opt into simulated service-stored behavior. Users who need per-service-call persistence for recoverability (driver C) can enable it explicitly.

 ### Configuration Matrix

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

-| `UseProvidedChatClientAsIs` | `PersistChatHistoryAtEndOfRun` | Behavior |
+| `UseProvidedChatClientAsIs` | `RequirePerServiceCallChatHistoryPersistence` | Behavior |
 |---|---|---|
-| `false` (default) | `false` (default) | **Per-service-call persistence.** A `ChatHistoryPersistingChatClient` middleware is automatically injected into the chat client pipeline between `FunctionInvokingChatClient` and the leaf `IChatClient`. Messages are persisted after each service call. |
-| `true` | `false` | **User responsibility.** No middleware is injected because the user has provided a custom chat client stack. The user is responsible for ensuring correct persistence behavior (e.g., by including their own persisting middleware). |
-| `false` | `true` | **Per-run persistence with marking.** A `ChatHistoryPersistingChatClient` middleware is injected, but configured to *mark* messages with metadata rather than store them immediately. At the end of the run, marked messages are stored. Trailing `FunctionResultContent` is trimmed. |
-| `true` | `true` | **Per-run persistence with warning.** The system checks whether the custom chat client stack includes a `ChatHistoryPersistingChatClient`. If not, a warning is emitted (particularly relevant for workflow handoff scenarios where trimming cannot be guaranteed). If no `ChatHistoryPersistingChatClient` is preset, all messages are stored at the end of the run, otherwise marked messages are stored. |
+| `false` (default) | `false` (default) | **Per-run persistence.** Messages are persisted at the end of the full agent run via the `ChatHistoryProvider`. |
+| `false` | `true` | **Per-service-call persistence (simulated).** A `PerServiceCallChatHistoryPersistingChatClient` middleware is automatically injected into the chat client pipeline between `FunctionInvokingChatClient` and the leaf `IChatClient`. Messages are persisted after each service call. A sentinel `ConversationId` causes FIC to treat the conversation as service-managed. |
+| `true` | `false` | **Per-run persistence.** No middleware is injected because the user has provided a custom chat client stack. Messages are persisted at the end of the run. |
+| `true` | `true` | **User responsibility.** The system checks whether the custom chat client stack includes a `PerServiceCallChatHistoryPersistingChatClient`. If not, a warning is emitted — the user is expected to have added their own per-service-call persistence mechanism. End-of-run persistence is skipped. |

 ### Consequences

- Good, because the stored history matches the service's behavior by default for both timing and content, fully satisfying consistency (driver A).
- Good, because intermediate progress is preserved if the process is interrupted, satisfying recoverability (driver C).
- Good, because no separate `FunctionResultContent` trimming logic is needed in the default path, reducing complexity.
- Good, because marking persisted messages with metadata enables deduplication and aids debugging.
- Good, because warnings for custom chat client configurations without the persisting middleware help prevent silent failures in workflow handoff scenarios.
- Bad, because chat history may be left in an incomplete state if the run fails mid-loop (e.g., `FunctionCallContent` stored without corresponding `FunctionResultContent`), requiring manual recovery in rare cases.
- Bad, because the mental model is more complex for the default path: a single run may produce multiple history updates.
- Neutral, because users who prefer atomic run semantics can opt in to per-run persistence via `PersistChatHistoryAtEndOfRun = true`.
+- Good, because per-run persistence is atomic by default — chat history is only updated when the full run succeeds, satisfying driver B.
+- Good, because the default mental model is simple: one run = one history update, satisfying driver D.
+- Good, because users who opt into `RequirePerServiceCallChatHistoryPersistence` get stored history that matches the service's behavior for both timing and content, fully satisfying driver A.
+- Good, because per-service-call persistence preserves intermediate progress if the process is interrupted, satisfying driver C when opted in.
+- Good, because no separate `FunctionResultContent` trimming logic is needed when per-service-call persistence is active — it is naturally handled.
+- Good, because conflict detection (configurable via `ThrowOnChatHistoryProviderConflict`, `WarnOnChatHistoryProviderConflict`, `ClearOnChatHistoryProviderConflict`) prevents misconfiguration when a service returns a `ConversationId` alongside a configured `ChatHistoryProvider`.
+- Bad, because per-service-call persistence (when opted in) may leave chat history in an incomplete state if the run fails mid-loop (e.g., `FunctionCallContent` stored without corresponding `FunctionResultContent`), requiring manual recovery in rare cases.
+- Neutral, because users who want per-service-call consistency can opt in via `RequirePerServiceCallChatHistoryPersistence = true`, satisfying driver E.
 - Neutral, because increased write frequency from per-service-call persistence may impact performance for some storage backends; this can be mitigated with a caching decorator.

 ### Implementation Notes

 #### Conversation ID Consistency

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

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

- [PR #4762: Persist messages during function call loop](https://github.com/microsoft/agent-framework/pull/4762) — introduces `PersistChatHistoryAfterEachServiceCall` option and `ChatHistoryPersistingChatClient` decorator
- [PR #4792: Trim final FRC to match service storage](https://github.com/microsoft/agent-framework/pull/4792) — introduces `StoreFinalFunctionResultContent` option and `FilterFinalFunctionResultContent` logic
- [Issue #2889](https://github.com/microsoft/agent-framework/issues/2889) — original issue tracking chat history persistence during function call loops
@@ -462,7 +462,7 @@ class FoundryEvals:
 ### Azure AI: FoundryEvals Constants

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

 evaluators = [FoundryEvals.RELEVANCE, FoundryEvals.TOOL_CALL_ACCURACY]
 ```
@@ -0,0 +1,233 @@
+---
+status: proposed
+contact: eavanvalkenburg
+date: 2026-04-07
+deciders: TBD
+consulted:
+informed:
+---
+
+# CodeAct integration through backend-specific context providers and an `execute_code` tool
+
+## Introduction
+
+**CodeAct** is a pattern in which the model writes executable code — rather than emitting a fixed function-call JSON schema — to plan, transform data, and orchestrate tool calls inside a single sandbox invocation. Instead of requiring a separate model round-trip for every tool call, conditional branch, or data transformation, the model produces a short program that runs in a controlled runtime, calls host-provided tools through a `call_tool(...)` bridge, and returns structured results. This reduces latency, lowers token cost, and lets the model express richer multi-step logic that is difficult to capture in a flat tool-call sequence.
+
+Throughout this ADR, **CodeAct** is the primary term. **Code mode** and **programmatic tool calling** refer to the same capability.
+
+## Context and Problem Statement
+
+We need an architecture design that supports CodeAct in both Python and .NET. This is a necessary capability for the current generation of long-running agents, which need to plan, iterate, transform tool outputs, and execute bounded code inside a controlled runtime — for example, filtering a large result set, computing derived values, or chaining several tool calls with conditional logic — instead of requiring a separate model round-trip for each of those steps. The design should preserve the same behavioral contract across SDKs, but it does not need to use the same internal extension point in each runtime. We also want to standardize on Hyperlight as the initial backend, using the existing Python package and an anticipated .NET binding package once it is available.
+
+Throughout this ADR, **CodeAct** is the primary term. **Code mode** and **programmatic tool calling** refer to the same capability. This ADR uses **CodeAct** consistently.
+
+Model-generated code is treated as untrusted relative to the host process. This ADR assumes the selected backend provides the primary isolation boundary, while the framework is responsible for configuring approvals and capabilities, integrating telemetry, and translating outputs and failures into framework-native shapes. If a backend cannot provide isolation appropriate for its trust model, it is not a suitable CodeAct backend.
+
+The core design question is: **where should CodeAct integrate into the agent pipeline so that both SDKs can offer the same functionality without invasive changes to their core function-calling loops?**
+
+## Decision Drivers
+
+- CodeAct must shape the model-facing surface before model invocation, not only after the model has already chosen tools.
+- The design should let users control which tools are available through CodeAct and which remain regular tools only.
+- The design must preserve existing session, approval, telemetry, and tool invocation behavior as much as possible.
+- The design should define the minimum cross-SDK telemetry and failure semantics for `execute_code`, so Python and .NET do not diverge on basic observability or error handling.
+- The design must fit naturally into the extension points that already exist in each SDK.
+- The design must be safe for concurrent runs and must not rely on mutating shared agent configuration during invocation.
+- The chosen structure should allow multiple backend-specific providers to fit under the same conceptual design over time, even though Hyperlight is the initial target.
+- The abstraction should not assume that every backend is a VM-style sandbox; alternative execution models such as Pydantic's Monty should also fit.
+- The design should allow `execute_code` to be reused both as a tool-enabled CodeAct runtime and as a standard code interpreter tool implementation.
+- The design should remain open to alternative language/runtime modes, such as JavaScript on Hyperlight, rather than baking the abstraction to Python only.
+- The design should provide a portable way to configure sandbox capabilities such as file access and network access, including allow-listed outbound domains.
+- Using CodeAct should be optional, and installing its runtime or backend dependencies should also be optional.
+- Backend-specific dependencies should be isolated behind a small adapter so SDK code is not tightly coupled to an unstable package surface.
+
+## Considered Options
+
+- **Option 1**: Standardize on context provider-based CodeAct with a shared cross-SDK contract and backend-specific public types
+- **Option 2**: Implement CodeAct as a dedicated chat-client decorator/wrapper
+- **Option 3**: Integrate CodeAct directly into the function invocation layer/FunctionInvokingChatClient
+
+## Pros and Cons of the Options
+
+### Option 1: Standardize on context provider-based CodeAct with a shared cross-SDK contract and backend-specific public types
+
+This option uses `ContextProvider` in Python and `AIContextProvider` in .NET, but standardizes the public concept and behavior.
+In this option, the CodeAct tool set is provider-owned: only tools explicitly configured on the concrete CodeAct provider instance are available inside CodeAct, and the provider exposes direct CRUD-style management for tools, file mounts, and outbound network allow-list configuration rather than requiring a separate runtime setup object.
+The agent's direct tool surface remains separate. If a tool should be available both through CodeAct and as a normal direct tool, it is configured in both places.
+
+- Good, because both SDKs already have first-class provider concepts intended for per-invocation context shaping.
+- Good, because providers operate before model invocation, which is where CodeAct must add instructions and reshape tools.
+- Good, because this lets us preserve existing function invocation behavior rather than rewriting it.
+- Good, because slightly different internals are acceptable while the public behavior remains aligned.
+- Good, because convenience builder/decorator helpers can still be added later on top of the provider model without changing the core design.
+- Good, because backend-specific runtime logic can stay inside concrete provider implementations or internal helpers instead of being forced into a lowest-common-denominator public abstraction.
+- Good, because the same provider structure can support either an all-or-nothing tool surface or a mixed side-by-side tool surface.
+- Good, because users can keep some tools direct-only while allowing other tools to be used from inside CodeAct.
+- Good, because a provider-owned CodeAct tool registry avoids mutating or inferring the agent's direct tool surface and can work consistently in both SDKs.
+- Good, because the same conceptual design can remain open to `HyperlightCodeActProvider`, a future `MontyCodeActProvider`, and other backend-specific providers over time.
+- Good, because `execute_code` can evolve into multiple backend-specific runtime modes rather than being hard-wired to one Python-plus-tools mode.
+- Bad, because the provider indirection adds per-run overhead — snapshotting the tool registry, dispatching lifecycle hooks, and building instructions — that a deeper integration point could skip. In practice this overhead is negligible relative to model inference latency and sandbox startup cost.
+
+### Option 2: Implement CodeAct as a dedicated chat-client decorator/wrapper
+
+This option would introduce a CodeAct-specific chat-client decorator that injects instructions and tools directly into the chat request pipeline.
+
+- Good, because this is a natural fit for .NET's `DelegatingChatClient` pipeline.
+- Good, because it can also support advanced custom chat-client stacks.
+- Good, because backend-specific runtime selection could be hidden inside the decorator implementation.
+- Good, because the decorator could also encapsulate mode-specific instruction shaping for tool-enabled versus standalone interpreter behavior.
+- Good, because the decorator can decide per request whether the tool surface is exclusive or mixed.
+- Bad, because Python can support this by building a custom layering stack on top of a `Raw...Client` and swapping in a different `FunctionInvocationLayer`, but that composition path is more manual than the .NET `DelegatingChatClient` pipeline.
+- Bad, because it duplicates responsibilities already handled by provider abstractions.
+- Bad, because it makes CodeAct look more transport-specific than it really is.
+- Bad, because swappable backends and reusable interpreter or language modes become coupled to chat-client composition rather than modeled as first-class CodeAct concepts.
+
+### Option 3: Integrate CodeAct directly into the function invocation layer/FunctionInvokingChatClient
+
+This option would push CodeAct into Python's `FunctionInvocationLayer` and .NET's `FunctionInvokingChatClient` or related middleware.
+
+- Good, because it is close to tool execution and can observe concrete tool invocation behavior.
+- Good, because function middleware may still be useful later for auxiliary auditing or policy around sandbox-originated tool calls.
+- Bad, because this is the wrong layer for constructing the model-facing tool surface and prompt instructions.
+- Bad, because it does not naturally control whether the model sees an exclusive CodeAct tool surface or a mixed side-by-side tool surface.
+- Bad, because it would still require a second mechanism for hiding normal tools and advertising `execute_code`.
+- Bad, because it is a weak fit for standalone interpreter modes where no tool-calling loop is needed.
+- Bad, because backend selection and CodeAct mode behavior are orthogonal concerns that do not belong in the function invocation layer.
+- Bad, because `.NET` would become more tightly coupled to `FunctionInvokingChatClient`, which sits below the agent framework abstraction and is not the natural cross-SDK design seam.
+
+## Approval Model Options
+
+- **Option A**: Bundled approval for the `execute_code` invocation
+- **Option B**: Pre-execution inspection of `call_tool(...)` references before approving `execute_code`
+- **Option C**: Nested per-tool approvals during `execute_code`
+
+## Pros and Cons of the Approval Options
+
+### Option A: Bundled approval for the `execute_code` invocation
+
+This option grants approval once, before `execute_code` starts. Provider-owned tool calls made from inside that execution run under the same approval. The effective approval of `execute_code` is determined up front from the provider configuration rather than from inspecting which tools are actually called during execution.
+
+- Good, because it is the simplest model to explain and implement consistently in both SDKs.
+- Good, because it fits naturally with long-running CodeAct loops where repeated approval interruptions would be disruptive.
+- Good, because it does not require static code analysis before execution begins.
+- Good, because it keeps the first release focused on the provider integration rather than a more complex approval engine.
+- Bad, because approval is coarse-grained and may cover more activity than the user expected.
+- Bad, because it provides less visibility into which provider-owned tools or capabilities will be exercised during the run.
+
+### Option B: Pre-execution inspection of `call_tool(...)` references before approving `execute_code`
+
+This option inspects submitted code for statically discoverable `call_tool("tool_name", ...)` references before execution starts and uses that information to shape the approval request.
+
+- Good, because it can show users more detail up front while still keeping approval at a single pre-execution moment.
+- Good, because it matches the common case where tool names are spelled out directly in the generated code.
+- Good, because it can coexist with bundled approval as a more informative variant of the same UX.
+- Bad, because the analysis is inherently best-effort and cannot reliably predict dynamic behavior.
+- Bad, because it requires duplicated parsing or inspection logic that does not replace runtime enforcement.
+
+### Option C: Nested per-tool approvals during `execute_code`
+
+This option requests approval when sandboxed code actually attempts to invoke a provider-owned tool that requires approval.
+
+- Good, because it aligns approval with real behavior rather than predicted behavior.
+- Good, because it gives precise visibility into which provider-owned tools are being used.
+- Good, because it can allow some tool calls while rejecting others within the same execution.
+- Bad, because it interrupts long-running CodeAct flows and can degrade the user experience significantly.
+- Bad, because it requires more complex runtime plumbing and approval UX in both SDKs.
+- Bad, because repeated approval pauses may make CodeAct less useful for the exact long-running scenarios that motivate this feature.
+
+## Decision Outcomes
+
+### Decision 1: Integration seam and public structure
+
+Chosen option: **Option 1: Standardize on provider-based CodeAct with a shared cross-SDK contract and backend-specific public types**, because it is the only option that maps cleanly to both SDKs, lets us reshape instructions and tools before model invocation, and avoids invasive changes to the existing function invocation loops while still allowing multiple backend-specific providers and multiple runtime modes to fit under the same structure later.
+
+### Decision 2: Initial approval model
+
+Chosen option: **Option A: Bundled approval for the `execute_code` invocation**, because it is the smallest approval model that fits both SDKs, works well for long-running CodeAct flows, and does not force us to standardize a more complex inspection or policy engine in the first release.
+
+This follows the spirit of the current Python tool approval flow, where `FunctionTool` uses `approval_mode="always_require" | "never_require"` and the auto-invocation loop escalates the whole batch when any called tool requires approval.
+
+### Design summary
+
+We standardize the **public concept** of CodeAct across SDKs while allowing each SDK to use the extension point that fits it best.
+
+- Python uses a `ContextProvider`.
+- .NET uses an `AIContextProvider`.
+- The term **CodeAct context provider** is used throughout this ADR as a design concept, not as a required public base type. Public SDK APIs should prefer concrete backend-specific types such as `HyperlightCodeActProvider` rather than a public abstract `CodeActContextProvider` or a public `CodeActExecutor` parameter.
+- CodeAct support should ship as an optional package in each SDK rather than as part of the core package, so users who do not need CodeAct do not take on its installation and dependency footprint. That optional package may still depend on a few small, backward-compatible hooks in the host SDK's core agent pipeline.
+- There is no separate runtime setup object in the chosen design. Concrete providers manage their provider-owned CodeAct tool registry, file mounts, and outbound network allow-list configuration directly through CRUD-style methods on the provider itself.
+- At a high level, CodeAct is exposed through backend-specific context providers that contribute an `execute_code` tool, own the CodeAct-specific tool registry, and carry backend capability configuration such as filesystem and network access.
+- The initial approval model is bundled approval for `execute_code`, using the same `approval_mode="always_require" | "never_require"` vocabulary as regular tools.
+- The CodeAct provider exposes a default `approval_mode` for `execute_code`. If the provider default is `always_require`, `execute_code` is always treated as `always_require` regardless of the provider-owned tool registry. If the provider default is `never_require`, the effective approval for `execute_code` is derived from the provider-owned CodeAct tool registry captured for the run.
+- If every provider-owned CodeAct tool in that registry has `approval_mode="never_require"`, `execute_code` is treated as `never_require`. If any provider-owned CodeAct tool in that registry has `approval_mode="always_require"`, `execute_code` is treated as `always_require`, even if the generated code may not end up calling that tool.
+- Approval is granted before `execute_code` starts, and provider-owned tool calls made from inside that execution run under the same approval.
+- Direct-only agent tools do not affect the approval of `execute_code`; only the provider-owned CodeAct tool registry participates in that calculation.
+- This approval model is intentionally conservative. If one sensitive provider-owned tool forces `execute_code` to require approval more often than desired, the mitigation is to keep that tool direct-only or split it into a different provider/tool surface rather than trying to infer per-run tool usage up front.
+- Configuring filesystem and network capability state on the provider, including adding file mounts or outbound network allow-list entries, is itself the approval for those capabilities in the initial model.
+- Each `execute_code` invocation must start from a clean execution state; in-memory variables and other ephemeral interpreter/runtime state must not persist across separate calls. When a provider exposes a workspace, mounted files, or a writable artifact/output area, those files are the supported persistence mechanism across calls and are treated as external state rather than interpreter state.
+- Mutating the provider's tool registry or capability configuration while a run is in flight is allowed, but it only affects subsequent runs. Provider implementations must snapshot the effective state for each run and synchronize concurrent access so shared provider instances remain safe across concurrent runs.
+- The minimum cross-SDK telemetry contract is that `execute_code` is traced as a normal tool invocation nested inside the surrounding agent run, and provider-owned tool calls made from inside CodeAct continue to emit ordinary tool-invocation telemetry. Backend-specific resource metrics are optional extensions, not a required new top-level cross-SDK event model.
+- Timeout, out-of-memory, backend crash, and similar sandbox failures are all execution failures of `execute_code` and should surface as structured error results rather than backend-specific public DTOs. Partial textual or file outputs may be returned only when the backend can report them unambiguously; callers must not rely on partial-output recovery as a portable guarantee.
+- The provider-based structure preserves room for future pre-execution inspection and nested per-tool approvals if later experience shows they are needed.
+- Concrete backend-specific providers may still use small SDK-local helpers or adapters internally, but that split is an implementation detail rather than a public API requirement.
+
+Detailed language-specific implementation notes are specified in:
+
+- [Python implementation](../features/code_act/python-implementation.md)
+- [.NET implementation](../features/code_act/dotnet-implementation.md)
+
+### Minimal core hooks required by the optional package
+
+CodeAct remains optional at the package level, but the optional package depends on a small number of hooks that must live in the host SDK because the agent pipeline owns model invocation and per-run tool resolution.
+
+- Python depends on the existing `ContextProvider` lifecycle, `SessionContext.extend_instructions(...)`, `SessionContext.extend_tools(...)`, per-run runtime tool access via `SessionContext.options["tools"]`, and the shared `ApprovalMode` vocabulary used by `FunctionTool`.
+- .NET depends on the existing `AIContextProvider` seam, agent/runtime support for applying providers before model invocation, and the existing chat-client or function-invocation seams that concrete implementations use to contribute `execute_code`.
+
+These hooks are backward-compatible because they only expose or forward per-run state that core already owns. Behavior changes only when a concrete CodeAct provider opts in and uses them.
+
+### Concrete provider implementation contract
+
+The design does not require a public abstract `CodeActContextProvider` base class, but it does require a stable implementation contract for concrete providers.
+
+- Concrete providers should expose a standard capability surface at construction time, with SDK-appropriate naming for:
+  - approval mode
+  - workspace root
+  - file mounts
+  - allowed outbound targets plus any per-target method or policy restrictions needed by the backend
+- Separate public `filesystem_mode` / `network_mode` flags are not required by the cross-SDK contract. Filesystem access may be disabled implicitly until a workspace or file mounts are configured, and outbound network may be disabled implicitly until an allow-list or equivalent outbound policy entry is configured.
+- Concrete providers should expose direct CRUD-style methods for managing the provider-owned CodeAct tool registry, file mounts, and outbound network allow-list configuration, rather than requiring callers to construct a separate runtime setup object.
+- Concrete providers should implement their host SDK's provider lifecycle hooks to:
+  - build CodeAct instructions,
+  - add `execute_code`,
+  - snapshot the effective CodeAct tool registry and capability settings for the run,
+  - compute the effective approval requirement for `execute_code`,
+  - configure file access and network access for the backend,
+  - prepare or restore execution state,
+  - execute code,
+  - and translate backend output into framework-native content.
+- Any internal abstract/helper surface shared by multiple concrete providers should standardize responsibilities for:
+  - instruction construction,
+  - file-access configuration,
+  - network-access configuration,
+  - environment preparation/restoration,
+  - code execution,
+  - and output-to-content conversion.
+- Backend execution output should reuse existing framework-native content/message primitives rather than introducing backend-specific public result DTOs.
+
+## More Information
+
+### Related artifacts
+
+- Python implementation: [`docs/features/code_act/python-implementation.md`](../features/code_act/python-implementation.md)
+- .NET implementation: [`docs/features/code_act/dotnet-implementation.md`](../features/code_act/dotnet-implementation.md)
+- Python provider/session APIs: [`python/packages/core/agent_framework/_sessions.py`](../../python/packages/core/agent_framework/_sessions.py)
+- Python function invocation loop: [`python/packages/core/agent_framework/_tools.py`](../../python/packages/core/agent_framework/_tools.py)
+- .NET context provider abstraction: [`dotnet/src/Microsoft.Agents.AI.Abstractions/AIContextProvider.cs`](../../dotnet/src/Microsoft.Agents.AI.Abstractions/AIContextProvider.cs)
+- .NET agent integration for context providers: [`dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs`](../../dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs)
+- Optional .NET chat-client provider decorator: [`dotnet/src/Microsoft.Agents.AI/AIContextProviderDecorators/AIContextProviderChatClient.cs`](../../dotnet/src/Microsoft.Agents.AI/AIContextProviderDecorators/AIContextProviderChatClient.cs)
+- .NET function invocation middleware seam: [`dotnet/src/Microsoft.Agents.AI/FunctionInvocationDelegatingAgentBuilderExtensions.cs`](../../dotnet/src/Microsoft.Agents.AI/FunctionInvocationDelegatingAgentBuilderExtensions.cs)
+
+### Related decisions
+
+- [0015-agent-run-context](0015-agent-run-context.md)
+- [0016-python-context-middleware](0016-python-context-middleware.md)
@@ -0,0 +1,625 @@
+# CodeAct .NET implementation
+
+This document describes the .NET realization of the CodeAct design in
+[`docs/decisions/0024-codeact-integration.md`](../../decisions/0024-codeact-integration.md).
+
+This document is intentionally focused on the .NET design and public API surface.
+The initial public .NET type described here is `HyperlightCodeActProvider`. Future .NET backends, such as Monty, should follow the same conceptual model with their own concrete provider types rather than through a public abstract base class or a public executor parameter.
+
+## What is the goal of this feature?
+
+Goals:
+- .NET developers can enable CodeAct through an `AIContextProvider`-based integration.
+- Developers can configure a provider-owned CodeAct tool set that is separate from the agent's direct tool surface.
+- Developers can use the same `execute_code` concept for both tool-enabled CodeAct and a standard code interpreter tool implementation.
+- Developers can swap execution backends over time, starting with Hyperlight while keeping room for alternatives.
+- Developers can configure execution capabilities such as workspace mounts and outbound network allow lists in a portable way.
+
+Success Metric:
+- .NET samples exist for both a tool-enabled CodeAct mode and a standard interpreter mode.
+
+Implementation-free outcome:
+- A .NET developer can attach a backend-specific CodeAct provider, choose which tools are available inside CodeAct, and configure execution capabilities without rewriting the function invocation loop or ChatClient pipeline.
+
+## What is the problem being solved?
+
+The cross-SDK problem statement and decision rationale live in the [ADR](../../decisions/0024-codeact-integration.md). The items below narrow that statement to .NET-specific design concerns:
+
+- Today, the easiest way to prototype CodeAct in .NET is to manually configure an `AIFunction` and wire instructions — this is fragile and requires understanding internal sandbox lifecycle details.
+- There is no first-class .NET design that simultaneously covers Hyperlight-backed CodeAct now, future backend-specific providers, and both tool-enabled and interpreter modes.
+- Sandbox capabilities such as mounted file access and outbound network access need a portable configuration model instead of ad hoc backend-specific wiring.
+- Approval behavior needs to be explicit and configurable, mapping to .NET's existing `ApprovalRequiredAIFunction` wrapper mechanism.
+
+## API Changes
+
+### CodeAct contract
+
+#### Terminology
+
+- **CodeAct** is the primary term.
+- `execute_code` is the model-facing tool name used by the initial .NET provider in this spec.
+- Tool-enabled versus interpreter behavior is derived from the presence of CodeAct-managed tools, not from a separate public profile object.
+
+#### Provider-owned CodeAct tool registry
+
+A concrete .NET CodeAct provider owns the set of tools available through `call_tool(...)` inside CodeAct.
+
+Rules:
+- Only tools explicitly configured on the concrete provider instance are available inside CodeAct.
+- The provider must not infer its CodeAct-managed tool set from the agent's direct tool configuration (`ChatClientAgentOptions.Tools` or `AIContext.Tools`).
+- Exclusive versus mixed behavior is achieved by where tools are configured, not by rewriting the agent's direct tool list.
+
+Implications:
+- **CodeAct-only tool**: configured on the concrete CodeAct provider only.
+- **Direct-only tool**: configured on the agent only.
+- **Tool available both ways**: configured on both the agent and the concrete CodeAct provider.
+
+#### Managing tools and capabilities after provider construction
+
+There is no separate runtime setup object in the .NET design. CodeAct tools, file mounts, and outbound network allow-list state are managed directly on the provider through CRUD-style registry methods.
+
+Preferred pattern:
+- `AddTools(params AIFunction[] tools) -> void`
+- `GetTools() -> IReadOnlyList<AIFunction>`
+- `RemoveTools(params string[] names) -> void`
+- `ClearTools() -> void`
+- `AddFileMounts(params FileMount[] mounts) -> void`
+- `GetFileMounts() -> IReadOnlyList<FileMount>`
+- `RemoveFileMounts(params string[] mountPaths) -> void`
+- `ClearFileMounts() -> void`
+- `AddAllowedDomains(params AllowedDomain[] domains) -> void`
+- `GetAllowedDomains() -> IReadOnlyList<AllowedDomain>`
+- `RemoveAllowedDomains(params string[] targets) -> void`
+- `ClearAllowedDomains() -> void`
+
+Requirements:
+- The provider-owned CodeAct tool registry is keyed by tool name (from `AIFunction.Name`).
+- `AddTools(...)` adds new tools and replaces an existing provider-owned registration when the same tool name is added again.
+- `GetTools()` returns the provider's current configured CodeAct tool registry.
+- `RemoveTools(...)` removes provider-owned CodeAct tools by name.
+- `ClearTools()` removes all provider-owned CodeAct tools.
+- File mounts are keyed by sandbox mount path.
+- `AddFileMounts(...)` adds new file mounts and replaces an existing mount when the same mount path is added again.
+- `GetFileMounts()` returns the provider's current configured file mounts.
+- `RemoveFileMounts(...)` removes file mounts by mount path.
+- `ClearFileMounts()` removes all configured file mounts.
+- Allowed domains are keyed by normalized target string.
+- `AddAllowedDomains(...)` adds allow-list entries and replaces an existing entry when the same target is added again.
+- `GetAllowedDomains()` returns the current outbound allow-list entries.
+- `RemoveAllowedDomains(...)` removes allow-list entries by target.
+- `ClearAllowedDomains()` removes all configured allow-list entries.
+- Tool, file-mount, and network-allow-list mutations affect subsequent runs only; runs already in progress keep the snapshot captured at run start.
+- The provider must snapshot its effective tool registry and capability state at the start of each run so concurrent execution remains deterministic.
+
+#### Approval model
+
+The initial .NET design follows the ADR's bundled approval decision and maps to the existing `ApprovalRequiredAIFunction` wrapper from `Microsoft.Extensions.AI.Abstractions`:
+
+- The provider exposes a default `ApprovalMode` for `execute_code` (enum: `CodeActApprovalMode.AlwaysRequire` / `CodeActApprovalMode.NeverRequire`).
+
+Effective `execute_code` approval is computed as follows:
+
+- If the provider default is `AlwaysRequire`, `execute_code` requires approval.
+- If the provider default is `NeverRequire`, the provider evaluates the provider-owned CodeAct tool registry snapshot for that run.
+  - If every provider-owned CodeAct tool in that snapshot is not an `ApprovalRequiredAIFunction`, `execute_code` does not require approval.
+  - If any provider-owned CodeAct tool in that snapshot is an `ApprovalRequiredAIFunction`, `execute_code` requires approval, even if the generated code may not call that tool.
+- When the effective approval resolves to `AlwaysRequire`, the generated `execute_code` function is wrapped in `ApprovalRequiredAIFunction` before being added to the `AIContext.Tools`.
+- Provider-owned tool calls made through `call_tool(...)` during that execution run use the approval already determined for `execute_code`.
+- Direct-only agent tools are excluded from this calculation.
+- File and network capabilities do not create a separate runtime approval check in the initial model; configuring them on the provider is itself the approval for those capabilities.
+
+This is intentionally conservative and matches the shape of the existing .NET function-tool approval flow, where `ApprovalRequiredAIFunction` signals to the `ChatClientAgent` that user approval is needed before invocation.
+
+#### Shared execution flow
+
+On each run:
+1. `ProvideAIContextAsync(...)` snapshots the current CodeAct-managed tool registry and capability settings.
+2. Computes the effective approval requirement for `execute_code` from the provider default plus the snapshotted tool registry.
+3. Builds provider-defined instructions.
+4. Builds a run-scoped `execute_code` `AIFunction` from the snapshot (optionally wrapped in `ApprovalRequiredAIFunction`).
+5. Returns an `AIContext` containing the instructions and `execute_code` tool.
+6. When `execute_code` is invoked by the model, the run-scoped function creates or reuses an execution environment.
+7. If the current provider mode exposes host tools, `call_tool(...)` is bound only to the provider-owned tool registry snapshot.
+8. Code is executed and results converted to a JSON result string.
+
+Caching rules:
+- The Hyperlight backend supports snapshots: the provider caches a reusable clean snapshot after the first sandbox initialization.
+- No mutable per-run execution state may be shared across concurrent runs.
+- In-memory interpreter state does not persist across separate `execute_code` calls.
+- Configured workspace files, mounted files, and any writable artifact/output area are the supported persistence mechanism across calls when the backend exposes them.
+
+### .NET public API
+
+#### Core types
+
+```csharp
+/// <summary>
+/// Represents a host-to-sandbox file mount configuration.
+/// </summary>
+/// <param name="HostPath">Absolute or relative path on the host filesystem.</param>
+/// <param name="MountPath">Path inside the sandbox (e.g. "/input/data.csv").</param>
+public sealed record FileMount(string HostPath, string MountPath);
+
+/// <summary>
+/// Represents an outbound network allow-list entry.
+/// </summary>
+/// <param name="Target">URL or domain (e.g. "https://api.github.com").</param>
+/// <param name="Methods">
+/// Optional HTTP methods to allow (e.g. ["GET", "POST"]).
+/// Null allows all methods supported by the backend.
+/// </param>
+public sealed record AllowedDomain(string Target, IReadOnlyList<string>? Methods = null);
+
+/// <summary>
+/// Controls the approval behavior for execute_code invocations.
+/// </summary>
+public enum CodeActApprovalMode
+{
+    /// <summary>execute_code always requires user approval.</summary>
+    AlwaysRequire,
+
+    /// <summary>
+    /// Approval is derived from the provider-owned tool registry:
+    /// if any tool is an ApprovalRequiredAIFunction, execute_code requires approval.
+    /// </summary>
+    NeverRequire,
+}
+```
+
+#### HyperlightCodeActProvider
+
+```csharp
+/// <summary>
+/// An AIContextProvider that enables CodeAct execution through the
+/// Hyperlight sandbox backend.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This provider injects an <c>execute_code</c> tool into the model-facing
+/// tool surface and builds CodeAct guidance instructions. Guest code executed
+/// through <c>execute_code</c> runs in an isolated Hyperlight sandbox with
+/// snapshot/restore for clean state per invocation.
+/// </para>
+/// <para>
+/// If no CodeAct-managed tools are configured, the provider uses
+/// interpreter-style behavior. If one or more CodeAct-managed tools are
+/// configured, the provider uses tool-enabled behavior and exposes
+/// <c>call_tool(...)</c> inside the sandbox bound to the configured tools.
+/// </para>
+/// </remarks>
+public sealed class HyperlightCodeActProvider : AIContextProvider, IDisposable
+{
+    /// <summary>
+    /// Initializes a new HyperlightCodeActProvider.
+    /// </summary>
+    /// <param name="options">Configuration options for the provider.</param>
+    public HyperlightCodeActProvider(HyperlightCodeActProviderOptions options);
+
+    // ----- Tool registry -----
+
+    /// <summary>Adds tools to the provider-owned CodeAct tool registry.</summary>
+    public void AddTools(params AIFunction[] tools);
+
+    /// <summary>Returns the current CodeAct-managed tools.</summary>
+    public IReadOnlyList<AIFunction> GetTools();
+
+    /// <summary>Removes tools by name from the CodeAct tool registry.</summary>
+    public void RemoveTools(params string[] names);
+
+    /// <summary>Removes all CodeAct-managed tools.</summary>
+    public void ClearTools();
+
+    // ----- File mounts -----
+
+    /// <summary>Adds file mount configurations.</summary>
+    public void AddFileMounts(params FileMount[] mounts);
+
+    /// <summary>Returns the current file mount configurations.</summary>
+    public IReadOnlyList<FileMount> GetFileMounts();
+
+    /// <summary>Removes file mounts by sandbox mount path.</summary>
+    public void RemoveFileMounts(params string[] mountPaths);
+
+    /// <summary>Removes all file mount configurations.</summary>
+    public void ClearFileMounts();
+
+    // ----- Network allow-list -----
+
+    /// <summary>Adds outbound network allow-list entries.</summary>
+    public void AddAllowedDomains(params AllowedDomain[] domains);
+
+    /// <summary>Returns the current outbound allow-list entries.</summary>
+    public IReadOnlyList<AllowedDomain> GetAllowedDomains();
+
+    /// <summary>Removes allow-list entries by target.</summary>
+    public void RemoveAllowedDomains(params string[] targets);
+
+    /// <summary>Removes all outbound allow-list entries.</summary>
+    public void ClearAllowedDomains();
+
+    // ----- Lifecycle -----
+
+    /// <summary>Releases the sandbox and all associated native resources.</summary>
+    public void Dispose();
+}
+```
+
+#### HyperlightCodeActProviderOptions
+
+```csharp
+/// <summary>
+/// Configuration options for <see cref="HyperlightCodeActProvider"/>.
+/// </summary>
+public sealed class HyperlightCodeActProviderOptions
+{
+    /// <summary>
+    /// The sandbox backend to use. Default is <c>Wasm</c>.
+    /// </summary>
+    public SandboxBackend Backend { get; set; } = SandboxBackend.Wasm;
+
+    /// <summary>
+    /// Path to the guest module (.wasm or .aot file).
+    /// Required for the Wasm backend; not needed for JavaScript.
+    /// When null, the provider attempts to locate the default packaged
+    /// Python guest module.
+    /// </summary>
+    public string? ModulePath { get; set; }
+
+    /// <summary>
+    /// Guest heap size. Accepts human-readable strings ("50Mi", "2Gi")
+    /// or raw byte values. Null uses the backend default.
+    /// </summary>
+    public string? HeapSize { get; set; }
+
+    /// <summary>
+    /// Guest stack size. Accepts human-readable strings ("35Mi")
+    /// or raw byte values. Null uses the backend default.
+    /// </summary>
+    public string? StackSize { get; set; }
+
+    /// <summary>
+    /// Initial set of CodeAct-managed tools available inside the sandbox.
+    /// </summary>
+    public IEnumerable<AIFunction>? Tools { get; set; }
+
+    /// <summary>
+    /// Default approval mode for the execute_code tool.
+    /// Default is <see cref="CodeActApprovalMode.NeverRequire"/>.
+    /// </summary>
+    public CodeActApprovalMode ApprovalMode { get; set; } = CodeActApprovalMode.NeverRequire;
+
+    /// <summary>
+    /// Optional workspace root directory on the host.
+    /// When set, it is exposed as the sandbox's input directory.
+    /// </summary>
+    public string? WorkspaceRoot { get; set; }
+
+    /// <summary>
+    /// Initial file mount configurations.
+    /// </summary>
+    public IEnumerable<FileMount>? FileMounts { get; set; }
+
+    /// <summary>
+    /// Initial outbound network allow-list entries.
+    /// </summary>
+    public IEnumerable<AllowedDomain>? AllowedDomains { get; set; }
+
+    /// <summary>
+    /// State key used to store provider state in AgentSession.StateBag.
+    /// Defaults to "HyperlightCodeActProvider". Override when using
+    /// multiple provider instances on the same agent.
+    /// </summary>
+    public string? StateKey { get; set; }
+}
+```
+
+#### Provider implementation contract
+
+The concrete provider plugs into the existing .NET `AIContextProvider` surface from `Microsoft.Agents.AI.Abstractions`.
+
+Required override:
+- `ProvideAIContextAsync(InvokingContext, CancellationToken) -> ValueTask<AIContext>`
+
+`ProvideAIContextAsync(...)` is responsible for:
+- snapshotting the current CodeAct-managed tool registry and capability settings for the run,
+- computing the effective approval requirement for `execute_code` from the provider default and the snapshotted tool registry,
+- building a short CodeAct guidance instruction string,
+- building a run-scoped `execute_code` `AIFunction` from the snapshot,
+- optionally wrapping it in `ApprovalRequiredAIFunction` when approval is required,
+- and returning an `AIContext` with `Instructions` and `Tools` set.
+
+These steps run on every invocation rather than once at construction time because the provider supports CRUD mutations between runs, concurrent runs need independent snapshots, and the effective approval and instructions depend on the tool registry state captured at run start.
+
+The provider overrides `StateKeys` to return the configured `StateKey` from options, enabling multiple provider instances on the same agent without key collisions.
+
+Mutating the provider after `ProvideAIContextAsync(...)` has captured a run-scoped snapshot is allowed, but it affects subsequent runs only. Provider implementations synchronize state capture and CRUD operations so shared provider instances remain safe across concurrent runs.
+
+#### AIFunction-to-sandbox tool bridging
+
+The Hyperlight sandbox's `RegisterTool(name, Func<string, string>)` accepts a synchronous JSON-in / JSON-out delegate. Provider-owned CodeAct tools are `AIFunction` instances that are async and cancellation-aware.
+
+Bridging strategy:
+- At sandbox initialization time, the provider registers each CodeAct-managed tool with the sandbox using the raw JSON overload: `RegisterTool(name, Func<string, string>)`.
+- When the sandbox guest calls `call_tool("name", ...)`, the bridge delegate:
+  1. Deserializes the JSON arguments.
+  2. Invokes `AIFunction.InvokeAsync(...)` synchronously (via `GetAwaiter().GetResult()`) since the sandbox FFI callback is inherently synchronous.
+  3. Serializes the result back to JSON.
+- This sync-over-async bridge is a known pragmatic trade-off constrained by the Hyperlight FFI boundary. It is safe because:
+  - Sandbox execution already runs on the thread pool (via `Task.Run`).
+  - The FFI callback runs on a worker thread with no synchronization context.
+- If the Hyperlight .NET SDK later adds async tool registration, the bridge should migrate to that.
+
+#### Runtime behavior
+
+- `ProvideAIContextAsync(...)` adds a short CodeAct guidance block through `AIContext.Instructions`.
+- `ProvideAIContextAsync(...)` adds `execute_code` through `AIContext.Tools`.
+- The detailed `call_tool(...)`, sandbox-tool, and capability guidance is carried by the `execute_code` function's `Description`.
+- `execute_code` invokes the configured Hyperlight sandbox guest.
+- If the current CodeAct tool registry snapshot is non-empty, the runtime injects `call_tool(...)` bound to the provider-owned tool registry.
+- The provider does not inspect or mutate the agent's `ChatClientAgentOptions.Tools` or the incoming `AIContext.Tools` to determine its CodeAct tool set.
+- The provider snapshots the current CodeAct tool registry and capability state at run start, so later registry and allow-list mutations only affect future runs.
+- Interpreter versus tool-enabled behavior is derived from the presence of CodeAct-managed tools.
+- `execute_code` is traced like a normal tool invocation within the surrounding agent run.
+
+#### Backend integration
+
+Initial public provider:
+- `HyperlightCodeActProvider`
+
+Backend-specific notes:
+- **Hyperlight**
+  - The provider internally creates a `SandboxBuilder` from the options and uses the `Sandbox` API from `HyperlightSandbox.Api`.
+  - The provider uses snapshot/restore to ensure clean execution state per `execute_code` invocation: a "warm" snapshot is taken after the first no-op initialization run, and restored before each subsequent execution.
+  - File access maps to Hyperlight Sandbox's `WithInputDir()` / `WithOutputDir()` / `WithTempOutput()` capability model.
+  - Network access is denied by default and is enabled through `Sandbox.AllowDomain(...)` per-target allow-list entries.
+  - Guest module resolution: if `ModulePath` is null for the Wasm backend, the provider attempts to locate a packaged Python guest module (equivalent to the Python SDK's `python_guest.path` resolution).
+
+#### Capability handling
+
+Capabilities are first-class `HyperlightCodeActProviderOptions` properties and provider-managed CRUD surfaces:
+- `WorkspaceRoot`
+- `FileMounts`
+- `AllowedDomains`
+
+Enabling access means:
+- Configuring `WorkspaceRoot` or any `FileMounts` enables the sandbox filesystem surface exposed through `/input` and `/output`.
+- Leaving both `WorkspaceRoot` and `FileMounts` unset means no filesystem surface is configured.
+- Adding any `AllowedDomains` entry enables outbound access only for the configured targets; leaving it empty means network access is disabled without a separate network mode flag.
+
+Backends may implement stricter semantics than these top-level settings.
+
+#### Execution output representation
+
+Backend execution output maps to a JSON result string returned from the `execute_code` `AIFunction`:
+
+```json
+{
+  "stdout": "Hello world\n",
+  "stderr": "",
+  "exit_code": 0,
+  "success": true
+}
+```
+
+Execution failures should surface readable error text in the `stderr` field and a non-zero `exit_code`. Timeouts, out-of-memory conditions, backend crashes, and similar sandbox failures are all `execute_code` failures and should surface as structured error results. Partial textual or file outputs may be returned only when the backend can report them unambiguously.
+
+#### `execute_code` input contract
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "Code to execute using the provider's configured backend/runtime behavior."
+    }
+  },
+  "required": ["code"]
+}
+```
+
+#### Thread safety and concurrency
+
+- All CRUD methods (`AddTools`, `RemoveTools`, `AddFileMounts`, etc.) are synchronized via an internal lock.
+- `ProvideAIContextAsync(...)` acquires the lock to snapshot current state, then releases it before building the run-scoped function. The run-scoped function closes over the immutable snapshot, not mutable provider state.
+- Concurrent `execute_code` invocations from different runs use independent sandbox instances or synchronized access to a shared sandbox with snapshot/restore.
+- Workspace directories (`WorkspaceRoot`, `FileMounts`) are external shared state: concurrent runs against the same workspace can race on files. This is the user's responsibility to manage (e.g., by using per-run output directories or separate provider instances).
+
+### HyperlightExecuteCodeFunction
+
+The provider package also exports a standalone `HyperlightExecuteCodeFunction` for direct-tool scenarios where a provider lifecycle is not needed. This is the .NET equivalent of the Python `HyperlightExecuteCodeTool`.
+
+```csharp
+/// <summary>
+/// A standalone execute_code AIFunction backed by a Hyperlight sandbox.
+/// Use this for manual/static wiring when the AIContextProvider lifecycle
+/// is not needed.
+/// </summary>
+public sealed class HyperlightExecuteCodeFunction : IDisposable
+{
+    /// <summary>
+    /// Creates a new standalone code execution function.
+    /// </summary>
+    /// <param name="options">Configuration options.</param>
+    public HyperlightExecuteCodeFunction(HyperlightCodeActProviderOptions options);
+
+    /// <summary>
+    /// Returns this as an AIFunction for direct registration on an agent.
+    /// When approval is required, the returned function is wrapped in
+    /// ApprovalRequiredAIFunction.
+    /// </summary>
+    public AIFunction AsAIFunction();
+
+    /// <summary>
+    /// Builds a CodeAct instruction string describing the available
+    /// tools and capabilities.
+    /// </summary>
+    /// <param name="toolsVisibleToModel">
+    /// When false, the instructions include full tool descriptions
+    /// (for use when tools are only accessible through CodeAct).
+    /// When true, instructions are abbreviated (tools are already
+    /// visible to the model as direct tools).
+    /// </param>
+    public string BuildInstructions(bool toolsVisibleToModel = false);
+
+    /// <summary>Releases sandbox resources.</summary>
+    public void Dispose();
+}
+```
+
+### Internal implementation structure
+
+The provider and standalone function share internal helpers:
+
+```
+Microsoft.Agents.AI.Hyperlight/
+├── HyperlightCodeActProvider.cs        // AIContextProvider implementation
+├── HyperlightCodeActProviderOptions.cs // Options record
+├── HyperlightExecuteCodeFunction.cs    // Standalone AIFunction for manual wiring
+├── FileMount.cs                        // File mount record
+├── AllowedDomain.cs                    // Network allow-list record
+├── CodeActApprovalMode.cs              // Approval enum
+├── Internal/
+│   ├── SandboxExecutor.cs              // Manages sandbox lifecycle, snapshot/restore
+│   ├── InstructionBuilder.cs           // Builds CodeAct instruction strings
+│   └── ToolBridge.cs                   // AIFunction ↔ Sandbox.RegisterTool adapter
+```
+
+`SandboxExecutor` encapsulates:
+- Creating and configuring a `Sandbox` from options.
+- Performing the initial no-op warm-up and snapshot.
+- Registering bridged tools via `ToolBridge`.
+- Restoring to the clean snapshot before each execution.
+- Translating `ExecutionResult` to a JSON string.
+
+`InstructionBuilder` generates:
+- A short CodeAct guidance block for `AIContext.Instructions`.
+- A detailed `execute_code` description including `call_tool(...)` signatures and capability documentation.
+
+`ToolBridge` handles:
+- Reflecting `AIFunction` metadata to build the sandbox tool registration.
+- The sync-over-async invocation bridge.
+
+## E2E Code Samples
+
+### Tool-enabled CodeAct mode
+
+```csharp
+var fetchDocs = AIFunctionFactory.Create(FetchDocs, name: "fetch_docs");
+var queryData = AIFunctionFactory.Create(QueryData, name: "query_data");
+var lookupUser = AIFunctionFactory.Create(LookupUser, name: "lookup_user");
+
+var codeact = new HyperlightCodeActProvider(new HyperlightCodeActProviderOptions
+{
+    Tools = [fetchDocs, queryData],
+    WorkspaceRoot = "./workdir",
+    AllowedDomains = [new AllowedDomain("api.github.com", ["GET"])],
+});
+codeact.AddTools(lookupUser);
+
+var sendEmail = AIFunctionFactory.Create(SendEmail, name: "send_email");
+
+var agent = chatClient.AsAIAgent(
+    instructions: "You are a helpful assistant.",
+    options: new ChatClientAgentOptions
+    {
+        Tools = [sendEmail],  // direct-only tool
+        AIContextProviders = [codeact],
+    });
+
+await using var session = await agent.CreateSessionAsync();
+var response = await agent.InvokeAsync("Analyze the latest docs", session);
+```
+
+### Standard code interpreter mode
+
+```csharp
+var codeact = new HyperlightCodeActProvider(new HyperlightCodeActProviderOptions
+{
+    WorkspaceRoot = "./data",
+});
+
+var agent = chatClient.AsAIAgent(
+    instructions: "You are a code interpreter.",
+    options: new ChatClientAgentOptions
+    {
+        AIContextProviders = [codeact],
+    });
+```
+
+### Manual static wiring (no provider lifecycle)
+
+When the tool registry and capability configuration are fixed, the provider lifecycle can be skipped entirely. Build the `execute_code` function and instructions once and pass them directly to the agent:
+
+```csharp
+using var executeCode = new HyperlightExecuteCodeFunction(
+    new HyperlightCodeActProviderOptions
+    {
+        Tools = [fetchDocs, queryData],
+        WorkspaceRoot = "./workdir",
+        AllowedDomains = [new AllowedDomain("api.github.com", ["GET"])],
+    });
+
+var codeactInstructions = executeCode.BuildInstructions(toolsVisibleToModel: false);
+
+var agent = chatClient.AsAIAgent(
+    instructions: $"You are a helpful assistant.\n\n{codeactInstructions}",
+    options: new ChatClientAgentOptions
+    {
+        Tools = [sendEmail, executeCode.AsAIFunction()],
+    });
+```
+
+### With approval required
+
+```csharp
+var sensitiveAction = new ApprovalRequiredAIFunction(
+    AIFunctionFactory.Create(DeleteRecords, name: "delete_records"));
+
+var codeact = new HyperlightCodeActProvider(new HyperlightCodeActProviderOptions
+{
+    Tools = [fetchDocs, sensitiveAction],  // sensitiveAction triggers approval
+});
+
+// execute_code will be wrapped in ApprovalRequiredAIFunction because
+// at least one managed tool (delete_records) requires approval.
+var agent = chatClient.AsAIAgent(
+    instructions: "You are a helpful assistant.",
+    options: new ChatClientAgentOptions
+    {
+        AIContextProviders = [codeact],
+    });
+```
+
+## Relationship to hyperlight-sandbox .NET SDK
+
+This design depends on the .NET SDK being added in [hyperlight-dev/hyperlight-sandbox#46](https://github.com/hyperlight-dev/hyperlight-sandbox/pull/46). Key types consumed from that SDK:
+
+| hyperlight-sandbox type | Used for |
+|---|---|
+| `Sandbox` | Core sandbox lifecycle: `Run()`, `RegisterTool()`, `AllowDomain()`, `Snapshot()`, `Restore()` |
+| `SandboxBuilder` | Fluent sandbox construction from provider options |
+| `SandboxBackend` | Backend selection (Wasm, JavaScript) |
+| `ExecutionResult` | Capturing stdout, stderr, exit code from guest execution |
+| `SandboxSnapshot` | Checkpoint/restore for clean state per execution |
+
+The provider package (`Microsoft.Agents.AI.Hyperlight`) takes a NuGet dependency on `Hyperlight.HyperlightSandbox.Api` and `Microsoft.Extensions.AI.Abstractions`. It does **not** depend on `HyperlightSandbox.Extensions.AI` (`CodeExecutionTool`) — the provider implements its own sandbox lifecycle management with run-scoped snapshots to support concurrent invocations safely.
+
+## Package structure
+
+The CodeAct Hyperlight provider ships as an optional NuGet package:
+- **Package**: `Microsoft.Agents.AI.Hyperlight`
+- **Dependencies**:
+  - `Microsoft.Agents.AI.Abstractions` (for `AIContextProvider`, `AIContext`)
+  - `Microsoft.Extensions.AI.Abstractions` (for `AIFunction`, `ApprovalRequiredAIFunction`)
+  - `Hyperlight.HyperlightSandbox.Api` (for sandbox API)
+- **Target framework**: `net8.0`
+
+This keeps CodeAct and its native sandbox dependencies optional — users who do not need CodeAct do not take on the Hyperlight installation and dependency footprint.
+
+## Open questions
+
+1. **Guest module distribution**: How should the default Python guest module (`.aot` file) be distributed for .NET consumers? Options include a separate NuGet package with native assets, a runtime download, or requiring users to build/provide their own.
+2. **Async tool registration**: If the Hyperlight .NET SDK adds async tool callback support in a future release, the sync-over-async bridge should be replaced. This is tracked as a known technical debt item.
+3. **Output file access**: The Hyperlight sandbox exposes `GetOutputFiles()` and `OutputPath` for retrieving files written by guest code. The initial design returns these as part of the JSON result. A future iteration could surface output files as framework-native content (e.g., `DataContent` or URI references).
+4. **Multiple sandbox instances for concurrency**: The current design uses synchronized access to a single sandbox with snapshot/restore. An alternative pooling strategy (one sandbox per concurrent run) could improve throughput at the cost of memory. This is deferred to implementation time.
@@ -0,0 +1,385 @@
+# CodeAct Python implementation
+
+This document describes the Python realization of the CodeAct design in
+[`docs/decisions/0024-codeact-integration.md`](../../decisions/0024-codeact-integration.md).
+
+This document is intentionally focused on the Python design and public API surface.
+The initial public Python type described here is `HyperlightCodeActProvider`. Future Python backends, such as Monty, should follow the same conceptual model with their own concrete provider types rather than through a public abstract base class or a public executor parameter.
+
+## What is the goal of this feature?
+
+Goals:
+- Python developers can enable CodeAct through a `ContextProvider`-based integration.
+- Developers can configure a provider-owned CodeAct tool set that is separate from the agent's direct `tools=` surface.
+- Developers can use the same `execute_code` concept for both tool-enabled CodeAct and a standard code interpreter tool implementation.
+- Developers can swap execution backends over time, starting with Hyperlight while keeping room for alternatives such as Pydantic's Monty.
+- Developers can configure execution capabilities such as workspace mounts and outbound network allow lists in a portable way.
+
+Success Metric:
+- Python samples exist for both a tool-enabled CodeAct mode and a standard interpreter mode.
+
+Implementation-free outcome:
+- A Python developer can attach a backend-specific CodeAct provider, choose which tools are available inside CodeAct, and configure execution capabilities without rewriting the function invocation loop.
+
+## What is the problem being solved?
+
+The cross-SDK problem statement and decision rationale live in the [ADR](../../decisions/0024-codeact-integration.md). The items below narrow that statement to Python-specific design concerns:
+
+- Today, the easiest way to prototype CodeAct is to infer or reshape the agent's direct tool surface, which is fragile and hard to reason about.
+- In Python, inferring a CodeAct tool surface from generic agent tool configuration is fragile and hard to reason about.
+- There is no first-class Python design that simultaneously covers Hyperlight-backed CodeAct now, future backend-specific providers such as Monty, and both tool-enabled and interpreter modes.
+- Sandbox capabilities such as mounted file access and outbound network access need a portable configuration model instead of ad hoc backend-specific wiring.
+- Approval behavior needs to be explicit and configurable, especially when CodeAct and direct tool calling may both be available.
+
+## API Changes
+
+### CodeAct contract
+
+#### Terminology
+
+- **CodeAct** is the primary term.
+- **Code mode**, **codemode**, and **programmatic tool calling** refer to the same concept in this document.
+- `execute_code` is the model-facing tool name used by the initial Python providers in this spec.
+
+#### Provider-owned CodeAct tool registry
+
+A concrete Python CodeAct provider owns the set of tools available through `call_tool(...)` inside CodeAct.
+
+Rules:
+- Only tools explicitly configured on the concrete provider instance are available inside CodeAct.
+- The provider must not infer its CodeAct-managed tool set from the agent's direct `tools=` configuration.
+- Exclusive versus mixed behavior is achieved by where tools are configured, not by rewriting the agent's direct tool list.
+
+Implications:
+- **CodeAct-only tool**: configured on the concrete CodeAct provider only.
+- **Direct-only tool**: configured on the agent only.
+- **Tool available both ways**: configured on both the agent and the concrete CodeAct provider.
+
+#### Managing tools and capabilities after provider construction
+
+There is no separate runtime setup object in the Python design. CodeAct tools, file mounts, and outbound network allow-list state are managed directly on the provider through CRUD-style registry methods.
+
+Preferred pattern:
+- `add_tools(...) -> None`
+- `get_tools() -> Sequence[ToolTypes]`
+- `remove_tool(...) -> None`
+- `clear_tools() -> None`
+- `add_file_mounts(...) -> None`
+- `get_file_mounts() -> Sequence[FileMount]`
+- `remove_file_mount(...) -> None`
+- `clear_file_mounts() -> None`
+- `add_allowed_domains(...) -> None`
+- `get_allowed_domains() -> Sequence[AllowedDomain]`
+- `remove_allowed_domain(...) -> None`
+- `clear_allowed_domains() -> None`
+
+Requirements:
+- The provider-owned CodeAct tool registry is keyed by tool name.
+- `add_tools(...)` adds new tools and replaces an existing provider-owned registration when the same tool name is added again.
+- `get_tools()` returns the provider's current configured CodeAct tool registry.
+- `remove_tool(...)` removes provider-owned CodeAct tools by name.
+- `clear_tools()` removes all provider-owned CodeAct tools.
+- File mounts are keyed by sandbox mount path.
+- `add_file_mounts(...)` adds new file mounts and replaces an existing mount when the same mount path is added again.
+- `get_file_mounts()` returns the provider's current configured file mounts.
+- `remove_file_mount(...)` removes file mounts by mount path.
+- `clear_file_mounts()` removes all configured file mounts.
+- Allowed domains are keyed by normalized target string.
+- `add_allowed_domains(...)` adds allow-list entries and replaces an existing entry when the same target is added again.
+- `get_allowed_domains()` returns the current outbound allow-list entries.
+- `remove_allowed_domain(...)` removes allow-list entries by target.
+- `clear_allowed_domains()` removes all configured allow-list entries.
+- Tool, file-mount, and network-allow-list mutations affect subsequent runs only; runs already in progress keep the snapshot captured at run start.
+- The provider must snapshot its effective tool registry and capability state at the start of each run so concurrent execution remains deterministic.
+
+#### Approval model
+
+The initial Python design follows the ADR's initial approval decision and reuses the existing tool approval vocabulary from `agent_framework._tools`:
+
+- `approval_mode="always_require"`
+- `approval_mode="never_require"`
+
+The provider exposes a default `approval_mode` for `execute_code`.
+
+Effective `execute_code` approval is computed as follows:
+
+- If the provider default is `always_require`, `execute_code` requires approval.
+- If the provider default is `never_require`, the provider evaluates the provider-owned CodeAct tool registry snapshot for that run.
+- If every provider-owned CodeAct tool in that snapshot is `never_require`, `execute_code` is `never_require`.
+- If any provider-owned CodeAct tool in that snapshot is `always_require`, `execute_code` is `always_require`, even if the generated code may not call that tool.
+- Provider-owned tool calls made through `call_tool(...)` during that execution run use the approval already determined for `execute_code`.
+- Direct-only agent tools are excluded from this calculation.
+- File and network capabilities do not create a separate runtime approval check in the initial model; configuring them on the provider, including adding file mounts or outbound network allow-list entries, is itself the approval for those capabilities.
+
+This is intentionally conservative and matches the shape of the current function-tool approval flow, where `FunctionTool` uses `always_require` / `never_require` and the auto-invocation loop escalates the whole batch if any called tool requires approval.
+
+If one sensitive provider-owned tool causes `execute_code` to require approval more often than desired, the mitigation is to keep that tool direct-only or expose it through a different CodeAct provider/tool surface. The initial model does not try to infer whether generated code will actually call that tool before approval.
+
+If the framework later standardizes pre-execution inspection or nested per-tool approvals, the Python provider surface can grow to expose that explicitly. The initial design does not assume that those extra modes are required.
+
+#### Shared execution flow
+
+On each run:
+1. Resolve the provider's backend/runtime behavior, capabilities, provider default `approval_mode`, and provider-owned tool registry.
+2. Compute the effective approval requirement for `execute_code` from the provider default plus the provider-owned tool registry snapshot.
+3. Build provider-defined instructions.
+4. Add `execute_code` to the model-facing tool surface.
+5. Invoke the underlying model.
+6. When `execute_code` is called, create or reuse an execution environment keyed by provider type, backend setup identity, capability configuration, and provider-owned tool signature.
+7. If the current provider mode exposes host tools, expose `call_tool(...)` bound only to the provider-owned tool registry.
+8. Execute code and convert results to framework-native content objects.
+
+Caching rules:
+- Backends that support snapshots may cache a reusable clean snapshot.
+- Backends that do not support snapshots may still cache warm initialization artifacts.
+- No mutable per-run execution state may be shared across concurrent runs.
+- In-memory interpreter state does not persist across separate `execute_code` calls.
+- Configured workspace files, mounted files, and any writable artifact/output area are the supported persistence mechanism across calls when the backend exposes them.
+
+### Python public API
+
+#### Core types
+
+```python
+class FileMount(NamedTuple):
+    host_path: str | Path
+    mount_path: str
+
+FileMountInput = str | tuple[str | Path, str] | FileMount
+
+
+class AllowedDomain(NamedTuple):
+    target: str
+    methods: tuple[str, ...] | None = None
+
+
+AllowedDomainInput = str | tuple[str, str | Sequence[str]] | AllowedDomain
+
+
+class HyperlightCodeActProvider(ContextProvider):
+    def __init__(
+        self,
+        source_id: str = "hyperlight_codeact",
+        *,
+        backend: str = "wasm",
+        module: str | None = "python_guest.path",
+        module_path: str | None = None,
+        tools: ToolTypes | None = None,
+        approval_mode: Literal["always_require", "never_require"] = "never_require",
+        workspace_root: Path | None = None,
+        file_mounts: Sequence[FileMountInput] = (),
+        allowed_domains: Sequence[AllowedDomainInput] = (),
+    ) -> None: ...
+
+    def add_tools(self, tools: ToolTypes | Sequence[ToolTypes]) -> None: ...
+    def get_tools(self) -> Sequence[ToolTypes]: ...
+    def remove_tool(self, name: str) -> None: ...
+    def clear_tools(self) -> None: ...
+    def add_file_mounts(self, mounts: FileMountInput | Sequence[FileMountInput]) -> None: ...
+    def get_file_mounts(self) -> Sequence[FileMount]: ...
+    def remove_file_mount(self, mount_path: str) -> None: ...
+    def clear_file_mounts(self) -> None: ...
+    def add_allowed_domains(self, domains: AllowedDomainInput | Sequence[AllowedDomainInput]) -> None: ...
+    def get_allowed_domains(self) -> Sequence[AllowedDomain]: ...
+    def remove_allowed_domain(self, domain: str) -> None: ...
+    def clear_allowed_domains(self) -> None: ...
+```
+
+`file_mounts` accepts three equivalent input forms:
+- `"data/report.csv"` uses the same relative path on the host and in the sandbox.
+- `("fixtures/users.json", "data/users.json")` or `(Path("fixtures/users.json"), "data/users.json")` uses distinct host and sandbox paths.
+- `FileMount(Path("fixtures/users.json"), "data/users.json")` is the named-tuple form of the explicit pair.
+
+`allowed_domains` accepts three equivalent input forms:
+- `"github.com"` allows that target with all backend-supported methods.
+- `("github.com", "GET")` or `("github.com", ["GET", "HEAD"])` uses an explicit per-target method list.
+- `AllowedDomain("github.com", ("GET", "HEAD"))` is the named-tuple form of the explicit entry.
+
+No public abstract `CodeActContextProvider` base or public `executor=` parameter is required for the initial Python API.
+
+The initial alpha package also exports a standalone `HyperlightExecuteCodeTool`
+for direct-tool scenarios where a provider is not needed. That standalone tool
+should advertise `call_tool(...)`, the registered sandbox tools, and capability
+state through its own `description` rather than requiring separate agent
+instructions.
+
+Provider modes:
+- If no CodeAct-managed tools are configured, `HyperlightCodeActProvider` uses interpreter-style behavior.
+- If one or more CodeAct-managed tools are configured, `HyperlightCodeActProvider` uses tool-enabled behavior.
+
+#### Python provider implementation contract
+
+The concrete provider plugs into the existing Python `ContextProvider` surface from `agent_framework._sessions`.
+
+The Hyperlight package also depends on a small set of core hooks that must remain available from `agent-framework-core`:
+- `ContextProvider.before_run(...)`
+- `SessionContext.extend_instructions(...)`
+- `SessionContext.extend_tools(...)`
+- per-run runtime tool access via `SessionContext.options["tools"]`
+- the shared `ApprovalMode` vocabulary used by `FunctionTool`
+
+Required lifecycle hook:
+- `before_run(*, agent, session, context, state) -> None`
+
+Optional lifecycle hook:
+- `after_run(*, agent, session, context, state) -> None`
+
+`before_run(...)` is responsible for:
+- snapshotting the current CodeAct-managed tool registry and capability settings for the run,
+- computing the effective approval requirement for `execute_code` from the provider default and the snapshotted tool registry,
+- adding a short CodeAct guidance block,
+- adding `execute_code` to the run through `SessionContext.extend_tools(...)`,
+- and wiring any backend-specific execution state needed for the run.
+
+These steps run on every invocation rather than once at construction time because the provider supports CRUD mutations between runs, concurrent runs need independent snapshots, and the effective approval and instructions depend on the tool registry state captured at run start. When the tool registry and capability configuration are fixed for the lifetime of the agent, the manual wiring pattern (see `codeact_manual_wiring.py`) can be used instead, which passes the tool and instructions directly to the `Agent` constructor and avoids the per-run provider lifecycle entirely.
+
+If the provider stores anything in `state`, that value must stay JSON-serializable.
+
+Mutating the provider after `before_run(...)` has captured a run-scoped snapshot is allowed, but it affects subsequent runs only. Provider implementations should synchronize state capture and CRUD operations so shared provider instances remain safe across concurrent runs.
+
+`after_run(...)` is responsible for any backend-specific cleanup or post-processing that must happen after the model invocation completes.
+
+If shared internal helpers are introduced later for multiple concrete providers, they should standardize responsibilities for:
+- building instructions,
+- computing effective approval,
+- configuring file access,
+- configuring network access,
+- preparing or restoring execution state,
+- executing code,
+- and converting backend output into framework-native `Content`.
+
+#### Runtime behavior
+
+- `before_run(...)` adds a short CodeAct guidance block through `SessionContext.extend_instructions(...)`.
+- `before_run(...)` adds `execute_code` through `SessionContext.extend_tools(...)`.
+- The detailed `call_tool(...)`, sandbox-tool, and capability guidance is carried by `execute_code.description`.
+- `execute_code` invokes the configured Hyperlight sandbox guest.
+- If the current CodeAct tool registry is non-empty, the runtime injects `call_tool(...)` bound to the provider-owned tool registry.
+- The provider does not inspect or mutate `Agent.default_options["tools"]` or `context.options["tools"]` to determine its CodeAct tool set.
+- The provider snapshots the current CodeAct tool registry and capability state at run start, so later registry and allow-list mutations only affect future runs.
+- Interpreter versus tool-enabled behavior is derived from the concrete provider and the presence of CodeAct-managed tools, not from a separate public profile object.
+- `execute_code` should be traced like a normal tool invocation within the surrounding agent run, and provider-owned tool calls executed through `call_tool(...)` should continue to emit ordinary tool invocation telemetry.
+
+#### Backend integration
+
+Initial public provider:
+- `HyperlightCodeActProvider`
+
+Backend-specific notes:
+- **Hyperlight**
+  - Provider construction needs a guest artifact via `module`, which may be a packaged guest module name or a path to a compiled guest artifact.
+  - File access maps naturally to Hyperlight Sandbox's read-only `/input` and writable `/output` capability model.
+  - Network access is denied by default and is enabled through per-target allow-list entries.
+- **Monty**
+  - A future `MontyCodeActProvider` should be a separate public type rather than a `HyperlightCodeActProvider` mode.
+  - Monty does not expose built-in filesystem or network access directly inside the interpreter.
+  - File and URL access are mediated through host-provided external functions, so a Monty provider would need to translate provider settings into virtual files and allow-checked callbacks.
+  - Monty setup may also include backend-specific inputs such as `script_name`, optional type-check stubs, or restored snapshots.
+
+#### Capability handling
+
+Capabilities are first-class `HyperlightCodeActProvider` init parameters and provider-managed CRUD surfaces:
+- `workspace_root`
+- `file_mounts`
+- `allowed_domains`
+
+Concrete providers should normalize these settings internally. Hyperlight can map them directly to sandbox capabilities, while Monty must enforce them through host-mediated file and network functions and may apply stricter URL-level checks than the public provider surface expresses.
+
+Expected management split:
+- `workspace_root` remains a direct configuration value on the provider,
+- file mounts are managed through provider CRUD methods,
+- outbound allow-list entries are managed through provider CRUD methods.
+
+Enabling access means:
+- Configuring `workspace_root` or any `file_mounts` enables the sandbox filesystem surface exposed through `/input` and `/output`.
+- Leaving both `workspace_root` and `file_mounts` unset means no filesystem surface is configured.
+- Adding any `allowed_domains` entry enables outbound access only for the configured targets; leaving it empty means network access is disabled without a separate `network_mode` flag.
+- A string target allows all backend-supported methods for that target; an explicit tuple or `AllowedDomain` entry narrows the methods for that target.
+
+Backends may implement stricter semantics than these top-level settings. For example, Hyperlight naturally maps file access to `/input` and `/output`, while Monty would enforce equivalent policy through host-provided callbacks rather than direct interpreter I/O.
+
+#### Execution output representation
+
+Backend execution output should be translated into existing AF `Content` values rather than a custom `CodeActExecutionResult` type.
+
+Use the existing content model from `agent_framework._types`, for example:
+- `Content.from_code_interpreter_tool_result(outputs=[...])` to surface the overall result of sandboxed code execution,
+- `Content.from_text(...)` for plain textual output,
+- `Content.from_data(...)` or `Content.from_uri(...)` for generated files or binary artifacts,
+- `Content.from_error(...)` for execution failures,
+- and `Content.from_function_result(..., result=list[Content])` when surfacing the final result of `execute_code` through the normal tool result path.
+
+#### `execute_code` input contract
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "Code to execute using the provider's configured backend/runtime behavior."
+    }
+  },
+  "required": ["code"]
+}
+```
+
+Execution failures should surface readable error text and structured error `Content`, not a custom backend result object.
+
+Timeouts, out-of-memory conditions, backend crashes, and similar sandbox failures are all `execute_code` failures and should surface as structured error content. Partial textual or file outputs may be returned only when the backend can report them unambiguously; callers should not rely on partial-output recovery as a portable contract.
+
+## E2E Code Samples
+
+### Tool-enabled CodeAct mode
+
+```python
+codeact = HyperlightCodeActProvider(
+    tools=[fetch_docs, query_data],
+    workspace_root="./workdir",
+    allowed_domains=[("api.github.com", "GET")],
+)
+codeact.add_tools([lookup_user])
+
+agent = Agent(
+    client=client,
+    name="assistant",
+    tools=[send_email],  # direct-only tool
+    context_providers=[codeact],
+)
+```
+
+### Standard code interpreter mode
+
+```python
+codeact = HyperlightCodeActProvider(
+    workspace_root="./data",
+)
+
+agent = Agent(
+    client=client,
+    name="interpreter",
+    context_providers=[codeact],
+)
+```
+
+### Manual static wiring (no per-run provider lifecycle)
+
+When the tool registry and capability configuration are fixed, the provider lifecycle can be skipped entirely. Build the `execute_code` tool and instructions once and pass them directly to the agent:
+
+```python
+execute_code = HyperlightExecuteCodeTool(
+    tools=[fetch_docs, query_data],
+    workspace_root="./workdir",
+    allowed_domains=[("api.github.com", "GET")],
+    approval_mode="never_require",
+)
+
+codeact_instructions = execute_code.build_instructions(tools_visible_to_model=False)
+
+agent = Agent(
+    client=client,
+    name="assistant",
+    instructions=f"You are a helpful assistant.\n\n{codeact_instructions}",
+    tools=[send_email, execute_code],
+)
+```
@@ -177,7 +177,7 @@ This feature ports the vector store abstractions, embedding generator abstractio
 **Goal:** Add embedding generators to all existing AF provider packages that have chat clients.
 **Mergeable:** Yes — each is independent, added to existing provider packages.

-#### 2.1 — Azure AI Inference embedding (in `packages/azure-ai/`)
+#### 2.1 — Foundry inference embedding (in `packages/foundry/`)
 #### 2.2 — Ollama embedding (in `packages/ollama/`)
 #### 2.3 — Anthropic embedding (in `packages/anthropic/`)
 #### 2.4 — Bedrock embedding (in `packages/bedrock/`)
@@ -12,8 +12,8 @@ dotnet/
 │   ├── Microsoft.Agents.AI.Abstractions/         # Core AI agent abstractions
 │   ├── Microsoft.Agents.AI.A2A/                  # Agent-to-Agent (A2A) provider
 │   ├── Microsoft.Agents.AI.OpenAI/               # OpenAI provider
-│   ├── Microsoft.Agents.AI.AzureAI/              # Azure AI Foundry Agents (v2) provider
-│   ├── Microsoft.Agents.AI.AzureAI.Persistent/   # Legacy Azure AI Foundry Agents (v1) provider
+│   ├── Microsoft.Agents.AI.Foundry/               # Microsoft Foundry Agents (v2) provider
+│   ├── Microsoft.Agents.AI.AzureAI.Persistent/   # Legacy Microsoft Foundry Agents (v1) provider
 │   ├── Microsoft.Agents.AI.Anthropic/            # Anthropic provider
 │   ├── Microsoft.Agents.AI.Workflows/            # Workflow orchestration
 │   └── ...                                       # Other packages
@@ -0,0 +1,225 @@
+---
+name: verify-samples-tool
+description: How to use the verify-samples tool to run, verify, and manage sample definitions in the Agent Framework repository. Use this when adding, updating, or running sample verification.
+---
+
+# verify-samples Tool
+
+The `verify-samples` project (`dotnet/eng/verify-samples/`) is an automated tool that runs sample projects and verifies their output using deterministic checks and AI-powered verification.
+
+## Running verify-samples
+
+**Important:** By default, samples must be pre-built before running verify-samples. Build the solution first, or pass `--build` to build samples during the run:
+
+```bash
+cd dotnet
+dotnet build agent-framework-dotnet.slnx -f net10.0
+```
+
+Then run verify-samples:
+
+```bash
+# Run all samples across all categories
+dotnet run --project eng/verify-samples -- --log results.log --csv results.csv
+
+# Run a specific category
+dotnet run --project eng/verify-samples -- --category 02-agents --log results.log
+
+# Run specific samples by name
+dotnet run --project eng/verify-samples -- Agent_Step02_StructuredOutput Agent_Step09_AsFunctionTool
+
+# Control parallelism (default 8)
+dotnet run --project eng/verify-samples -- --parallel 8 --log results.log
+
+# Build samples during run (skips the need for a prior build step)
+# This may cause build conflicts as multiple samples are built in parallel, so use with caution
+dotnet run --project eng/verify-samples -- --build --log results.log
+
+# Combine options
+dotnet run --project eng/verify-samples -- --category 03-workflows --parallel 4 --log results.log --csv results.csv --md results.md
+```
+
+### Required Environment Variables
+
+The tool itself needs:
+- `AZURE_OPENAI_ENDPOINT` — for the AI verification agent
+- `AZURE_OPENAI_DEPLOYMENT_NAME` (optional, defaults to `gpt-5-mini`)
+
+Individual samples require their own env vars (e.g., `AZURE_AI_PROJECT_ENDPOINT`). The tool automatically checks and skips samples with missing env vars.
+
+### Output Files
+
+- `--log results.log` — detailed per-sample log with stdout/stderr, AI reasoning, and a summary
+- `--csv results.csv` — tabular summary with Sample, ProjectPath, Status, FailedChecks, and Failures columns
+- `--md results.md` — Markdown summary with results table and collapsible failure details (suitable for GitHub PR comments)
+
+## Sample Categories
+
+Definitions are in the `dotnet/eng/verify-samples/` directory:
+
+| Category | Config File | Registered Key |
+|----------|-------------|----------------|
+| 01-get-started | `GetStartedSamples.cs` | `01-get-started` |
+| 02-agents | `AgentsSamples.cs` | `02-agents` |
+| 03-workflows | `WorkflowSamples.cs` | `03-workflows` |
+
+Categories are registered in `VerifyOptions.cs` in the `s_sampleSets` dictionary.
+
+## SampleDefinition Properties
+
+Each sample is defined as a `SampleDefinition` in the appropriate config file. Key properties:
+
+```csharp
+new SampleDefinition
+{
+    // Required: Display name for the sample
+    Name = "Agent_Step02_StructuredOutput",
+
+    // Required: Relative path from dotnet/ to the sample project directory
+    ProjectPath = "samples/02-agents/Agents/Agent_Step02_StructuredOutput",
+
+    // Environment variables the sample requires (throws if missing)
+    RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+
+    // Environment variables with defaults that would prompt on console if unset
+    OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+
+    // Skip this sample with a reason (for structural issues only)
+    SkipReason = null, // or "Requires external service X."
+
+    // Deterministic checks: substrings that must appear in stdout
+    MustContain = ["=== Section Header ==="],
+
+    // Substrings that must NOT appear in stdout
+    MustNotContain = [],
+
+    // If true, only MustContain checks are used (no AI verification)
+    IsDeterministic = false,
+
+    // AI verification: natural-language descriptions of expected output
+    // Each entry describes one aspect to verify independently
+    ExpectedOutputDescription =
+    [
+        "The output should show structured person information with Name, Age, and Occupation fields.",
+        "The output should not contain error messages or stack traces.",
+    ],
+
+    // Stdin inputs to feed to the sample (for interactive samples)
+    Inputs = ["Y", "Y", "Y"],
+
+    // Delay between stdin inputs in ms (default 2000, increase for LLM calls between inputs)
+    InputDelayMs = 3000,
+}
+```
+
+## How to Add a New Sample Definition
+
+1. **Check the sample's Program.cs** to understand:
+   - What environment variables it reads (look for `GetEnvironmentVariable`)
+   - Whether it needs stdin input (look for `Console.ReadLine`, `Application.GetInput`)
+   - Whether it has an external loop (look for `EXIT` patterns in YAML workflows)
+   - What output it produces (section headers, markers, expected behavior)
+   - Whether it exits on its own or runs as a server
+
+2. **Choose the right verification strategy:**
+   - **Deterministic** (`IsDeterministic = true`): Use `MustContain` for samples with fixed output strings. No AI verification.
+   - **AI-verified** (default): Use `ExpectedOutputDescription` with semantic descriptions. Write expectations that are flexible enough for non-deterministic LLM output.
+   - **Both**: Use `MustContain` for fixed markers AND `ExpectedOutputDescription` for LLM-generated content.
+
+3. **Set `SkipReason` only for structural issues:**
+   - Web servers that don't exit
+   - Multi-process client/server architectures
+   - Samples requiring external infrastructure (MCP servers you can't reach, Docker, etc.)
+   - Do NOT skip for missing env vars — the tool checks those dynamically.
+
+4. **For interactive samples, provide `Inputs`:**
+   - Samples using `Application.GetInput(args)` need one initial input
+   - Samples with `Console.ReadLine()` approval loops need `"Y"` inputs
+   - YAML workflows with `externalLoop` need `"EXIT"` as the last input
+   - Set `InputDelayMs` to 3000-8000ms for samples with LLM calls between inputs
+
+5. **Add the definition** to the appropriate config file (e.g., `AgentsSamples.cs`) in the `All` list.
+
+6. **Register new categories** (if needed) in `VerifyOptions.cs` `s_sampleSets` dictionary.
+
+### Writing Good ExpectedOutputDescription
+
+- Write descriptions that are **semantically flexible** — LLM output varies between runs
+- Each array entry should describe **one independent aspect** to verify
+- Always include `"The output should not contain error messages or stack traces."` as the last entry
+- Avoid exact wording expectations — use "should mention", "should contain information about", "should show"
+- Bad: `"The output should say 'The weather in Amsterdam is cloudy with a high of 15°C'"`
+- Good: `"The output should contain weather information about Amsterdam mentioning cloudy weather with a high of 15°C."`
+
+### Example: Simple LLM Sample
+
+```csharp
+new SampleDefinition
+{
+    Name = "Agent_With_AzureOpenAIChatCompletion",
+    ProjectPath = "samples/02-agents/AgentProviders/Agent_With_AzureOpenAIChatCompletion",
+    RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+    OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+    ExpectedOutputDescription =
+    [
+        "The output should contain a joke about a pirate.",
+        "The output should not contain error messages or stack traces.",
+    ],
+},
+```
+
+### Example: Deterministic Sample
+
+```csharp
+new SampleDefinition
+{
+    Name = "Workflow_Declarative_GenerateCode",
+    ProjectPath = "samples/03-workflows/Declarative/GenerateCode",
+    IsDeterministic = true,
+    MustContain = ["WORKFLOW: Parsing", "WORKFLOW: Defined"],
+    ExpectedOutputDescription = ["The output should show a YAML workflow being parsed and C# code being generated from it."],
+},
+```
+
+### Example: Interactive Sample with Approval Loop
+
+```csharp
+new SampleDefinition
+{
+    Name = "FoundryAgent_Hosted_MCP",
+    ProjectPath = "samples/02-agents/ModelContextProtocol/FoundryAgent_Hosted_MCP",
+    RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+    OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+    Inputs = ["Y", "Y", "Y", "Y", "Y"],
+    InputDelayMs = 5000,
+    ExpectedOutputDescription = ["The output should show an agent using the Microsoft Learn MCP tool with approval prompts."],
+},
+```
+
+### Example: Declarative Workflow with External Loop
+
+```csharp
+new SampleDefinition
+{
+    Name = "Workflow_Declarative_FunctionTools",
+    ProjectPath = "samples/03-workflows/Declarative/FunctionTools",
+    RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+    OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+    Inputs = ["What are today's specials?", "EXIT"],
+    InputDelayMs = 8000,
+    ExpectedOutputDescription = ["The output should show a workflow calling function tools to answer a question about restaurant specials."],
+},
+```
+
+### Example: Skipped Sample
+
+```csharp
+new SampleDefinition
+{
+    Name = "Agent_MCP_Server",
+    ProjectPath = "samples/02-agents/ModelContextProtocol/Agent_MCP_Server",
+    RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+    OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+    SkipReason = "Runs as an MCP stdio server that does not exit on its own.",
+},
+```
@@ -29,13 +29,14 @@ using types like `IChatClient`, `FunctionInvokingChatClient`, `AITool`, `AIFunct

 ## Key Conventions

- **Encoding**: All new files must be saved with UTF-8 encoding with BOM (Byte Order Mark). This is required for `dotnet format` to work correctly.
+- **Command output capture**: When running `dotnet build`, `dotnet test`, `dotnet format`, or similar commands, redirect output to a temp file first (e.g., `dotnet build --tl:off 2>&1 | Out-File $env:TEMP\build.log`), then analyze the file as needed. This avoids re-running expensive commands when the initial analysis misses something.
+- **Encoding**: All new files must be saved with UTF-8 encoding with BOM (Byte Order Mark). This is required for `dotnet format` to work correctly. When using PowerShell `Set-Content`, always pass `-Encoding UTF8BOM` to preserve the BOM (e.g., `Set-Content $file $content -NoNewline -Encoding UTF8BOM`).
 - **Copyright header**: `// Copyright (c) Microsoft. All rights reserved.` at top of all `.cs` files
 - **XML docs**: Required for all public methods and classes
 - **Async**: Use `Async` suffix for methods returning `Task`/`ValueTask`
 - **Private classes**: Should be `sealed` unless subclassed
 - **Config**: Read from environment variables with `UPPER_SNAKE_CASE` naming
- **Tests**: Add Arrange/Act/Assert comments; use Moq for mocking
+- **Tests**: Add Arrange/Act/Assert comments; use Moq for mocking; test methods returning `Task`/`ValueTask` must use the `Async` suffix.

 ## Key Design Principles

@@ -17,6 +17,7 @@

  <PropertyGroup>
    <IsReleaseCandidate>false</IsReleaseCandidate>
+    <IsReleased>false</IsReleased>
  </PropertyGroup>
  
  <PropertyGroup>
@@ -4,8 +4,9 @@
  <!-- https://learn.microsoft.com/en-us/nuget/consume-packages/Central-Package-Management -->
  <Sdk Name="Microsoft.Build.CentralPackageVersions" Version="2.1.3" />
  <!-- Only run 'dotnet format' on dev machines, Release builds. Skip on GitHub Actions -->
-  <!-- as this runs in its own Actions job. -->
-  <Target Name="DotnetFormatOnBuild" BeforeTargets="Build" Condition=" '$(Configuration)' == 'Release' AND '$(GITHUB_ACTIONS)' == '' ">
+  <!-- as this runs in its own Actions job. Only run for net10.0 target frameworks since the dotnet format command -->
+  <!-- already formats all target frameworks in project. Otherwise it will run format x times x where x is the number of target frameworks -->
+  <Target Name="DotnetFormatOnBuild" BeforeTargets="Build" Condition=" '$(Configuration)' == 'Release' AND '$(GITHUB_ACTIONS)' == '' AND '$(TargetFramework)' == 'net10.0' ">
    <Message Text="Running dotnet format" Importance="high" />
    <Exec Command="dotnet format --no-restore -v diag $(ProjectFileName)" />
  </Target>
@@ -7,53 +7,56 @@
  </PropertyGroup>
  <PropertyGroup>
    <!-- Aspire -->
-    <AspireAppHostSdkVersion>13.0.2</AspireAppHostSdkVersion>
+    <AspireAppHostSdkVersion>13.1.0</AspireAppHostSdkVersion>
  </PropertyGroup>
  <ItemGroup>
    <!-- Aspire.* -->
-    <PackageVersion Include="Anthropic" Version="12.8.0" />
-    <PackageVersion Include="Anthropic.Foundry" Version="0.4.2" />
+    <PackageVersion Include="Anthropic" Version="12.13.0" />
+    <PackageVersion Include="Anthropic.Foundry" Version="0.5.0" />
+    <PackageVersion Include="Aspire.Hosting" Version="$(AspireAppHostSdkVersion)" />
    <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="13.0.0-preview.1.25560.3" />
+    <PackageVersion Include="Aspire.Azure.AI.Inference" Version="13.1.0-preview.1.25616.3" />
+    <PackageVersion Include="Aspire.Hosting.Azure.AIFoundry" Version="13.1.0-preview.1.25616.3" />
    <PackageVersion Include="Aspire.Hosting.AppHost" Version="$(AspireAppHostSdkVersion)" />
    <PackageVersion Include="Aspire.Hosting.Azure.CognitiveServices" Version="$(AspireAppHostSdkVersion)" />
    <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
    <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
    <!-- Azure.* -->
-    <PackageVersion Include="Azure.AI.Projects" Version="2.0.0-beta.2" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.0.0" />
    <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.10" />
    <PackageVersion Include="Azure.AI.OpenAI" Version="2.9.0-beta.1" />
-    <PackageVersion Include="Azure.Identity" Version="1.19.0" />
+    <PackageVersion Include="Azure.Identity" Version="1.20.0" />
    <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.4.0" />
    <!-- Google Gemini  -->
-    <PackageVersion Include="Google.GenAI" Version="0.11.0" />
+    <PackageVersion Include="Google.GenAI" Version="1.6.0" />
    <PackageVersion Include="Mscc.GenerativeAI.Microsoft" Version="2.9.3" />
    <!-- Microsoft.Azure.* -->
    <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.54.0" />
    <!-- Newtonsoft.Json -->
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
    <!-- System.* -->
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.4" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.6" />
    <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
    <PackageVersion Include="Microsoft.Bcl.Memory" Version="10.0.4" />
-    <PackageVersion Include="System.ClientModel" Version="1.9.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.10.0" />
    <PackageVersion Include="System.CodeDom" Version="10.0.0" />
    <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
    <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
-    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.4" />
+    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.6" />
    <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.4" />
    <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />
    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.4" />
-    <PackageVersion Include="System.Text.Json" Version="10.0.4" />
-    <PackageVersion Include="System.Threading.Channels" Version="10.0.4" />
+    <PackageVersion Include="System.Text.Json" Version="10.0.6" />
+    <PackageVersion Include="System.Threading.Channels" Version="10.0.6" />
    <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
    <PackageVersion Include="System.Net.Security" Version="4.3.2" />
    <!-- OpenTelemetry -->
-    <PackageVersion Include="OpenTelemetry" Version="1.13.1" />
-    <PackageVersion Include="OpenTelemetry.Api" Version="1.13.1" />
-    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.13.1" />
-    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.13.1" />
-    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.13.1" />
-    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry" Version="1.14.0" />
+    <PackageVersion Include="OpenTelemetry.Api" Version="1.14.0" />
+    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.14.0" />
+    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.14.0" />
+    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.14.0" />
+    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.14.0" />
    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.13.0" />
    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.13.0" />
    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.13.0" />
@@ -63,37 +66,31 @@
    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
    <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.4.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.4.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.5.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.5.0" />
    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.4.0" />
    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.4.0" />
    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Safety" Version="10.3.0-preview.1.26109.11" />
-    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.4.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.5.0" />
    <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Compliance.Abstractions" Version="10.4.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.4" />
-    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Compliance.Abstractions" Version="10.5.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.6" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.1" />
    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.4" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.6" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.1" />
    <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
    <!-- Vector Stores -->
    <PackageVersion Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.67.0-preview" />
    <PackageVersion Include="Microsoft.SemanticKernel.Connectors.Qdrant" Version="1.67.0-preview" />
-    <!-- Semantic Kernel -->
-    <PackageVersion Include="Microsoft.SemanticKernel" Version="1.67.0" />
-    <PackageVersion Include="Microsoft.SemanticKernel.Agents.Core" Version="1.67.0" />
-    <PackageVersion Include="Microsoft.SemanticKernel.Agents.OpenAI" Version="1.67.0-preview" />
-    <PackageVersion Include="Microsoft.SemanticKernel.Agents.AzureAI" Version="1.67.0-preview" />
-    <PackageVersion Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.67.0" />
    <!-- Agent SDKs -->
    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.29" />
    <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
@@ -107,11 +104,10 @@
    <!-- MCP -->
    <PackageVersion Include="ModelContextProtocol" Version="1.1.0" />
    <!-- Inference SDKs -->
-    <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.5.1" />
    <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
    <PackageVersion Include="Microsoft.ML.Tokenizers" Version="2.0.0" />
    <PackageVersion Include="OllamaSharp" Version="5.4.8" />
-    <PackageVersion Include="OpenAI" Version="2.9.1" />
+    <PackageVersion Include="OpenAI" Version="2.10.0" />
    <!-- Identity -->
    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.83.1" />
    <!-- Workflows -->
@@ -126,7 +122,6 @@
    <PackageVersion Include="Microsoft.DurableTask.Worker.AzureManaged" Version="1.18.0" />
    <!-- Azure Functions -->
    <PackageVersion Include="Microsoft.Azure.Functions.Worker" Version="2.50.0" />
-    <PackageVersion Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="2.50.0" />
    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" Version="1.12.1" />
    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" Version="1.0.1" />
    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.3.0" />
@@ -4,9 +4,13 @@
    <BuildType Name="Publish" />
    <BuildType Name="Release" />
  </Configurations>
+  <Folder Name="/src/Aspire.Hosting.AgentFramework.DevUI/">
+    <Project Path="src/Aspire.Hosting.AgentFramework.DevUI/Aspire.Hosting.AgentFramework.DevUI.csproj" />
+  </Folder>
  <Folder Name="/Samples/">
    <File Path="samples/AGENTS.md" />
    <File Path="samples/README.md" />
+    <Project Path="eng/verify-samples/verify-samples.csproj" />
  </Folder>
  <Folder Name="/Samples/01-get-started/">
    <Project Path="samples/01-get-started/01_hello_agent/01_hello_agent.csproj" />
@@ -33,10 +37,15 @@
    <Project Path="samples/02-agents/AgentProviders/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj" />
    <Project Path="samples/02-agents/AgentProviders/Agent_With_Ollama/Agent_With_Ollama.csproj" />
    <Project Path="samples/02-agents/AgentProviders/Agent_With_ONNX/Agent_With_ONNX.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIAssistants/Agent_With_OpenAIAssistants.csproj" />
    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIChatCompletion/Agent_With_OpenAIChatCompletion.csproj" />
    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIResponses/Agent_With_OpenAIResponses.csproj" />
  </Folder>
+  <Folder Name="/Samples/05-end-to-end/DevUIAspireIntegration/">
+    <Project Path="samples/05-end-to-end/DevUIAspireIntegration/DevUIIntegration.AppHost/DevUIIntegration.AppHost.csproj" />
+    <Project Path="samples/05-end-to-end/DevUIAspireIntegration/DevUIIntegration.ServiceDefaults/DevUIIntegration.ServiceDefaults.csproj" />
+    <Project Path="samples/05-end-to-end/DevUIAspireIntegration/EditorAgent/EditorAgent.csproj" />
+    <Project Path="samples/05-end-to-end/DevUIAspireIntegration/WriterAgent/WriterAgent.csproj" />
+  </Folder>
  <Folder Name="/Samples/02-agents/Agents/">
    <File Path="samples/02-agents/Agents/README.md" />
    <Project Path="samples/02-agents/Agents/Agent_Step01_UsingFunctionToolsWithApprovals/Agent_Step01_UsingFunctionToolsWithApprovals.csproj" />
@@ -105,6 +114,10 @@
  <Folder Name="/Samples/02-agents/AgentSkills/">
    <File Path="samples/02-agents/AgentSkills/README.md" />
    <Project Path="samples/02-agents/AgentSkills/Agent_Step01_FileBasedSkills/Agent_Step01_FileBasedSkills.csproj" />
+    <Project Path="samples/02-agents/AgentSkills/Agent_Step02_CodeDefinedSkills/Agent_Step02_CodeDefinedSkills.csproj" />
+    <Project Path="samples/02-agents/AgentSkills/Agent_Step03_ClassBasedSkills/Agent_Step03_ClassBasedSkills.csproj" />
+    <Project Path="samples/02-agents/AgentSkills/Agent_Step04_MixedSkills/Agent_Step04_MixedSkills.csproj" />
+    <Project Path="samples/02-agents/AgentSkills/Agent_Step05_SkillsWithDI/Agent_Step05_SkillsWithDI.csproj" />
  </Folder>
  <Folder Name="/Samples/02-agents/AGUI/Step05_StateManagement/">
    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Client/Client.csproj" />
@@ -148,6 +161,13 @@
    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step21_WebSearch/Agent_Step21_WebSearch.csproj" />
    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step22_MemorySearch/Agent_Step22_MemorySearch.csproj" />
    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step23_LocalMCP/Agent_Step23_LocalMCP.csproj" />
+    <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step24_CodeInterpreterFileDownload/Agent_Step24_CodeInterpreterFileDownload.csproj" />
+  </Folder>
+  <Folder Name="/Samples/02-agents/Evaluation/">
+    <Project Path="samples/02-agents/Evaluation/Evaluation_SimpleEval/Evaluation_SimpleEval.csproj" />
+    <Project Path="samples/02-agents/Evaluation/Evaluation_CustomEvals/Evaluation_CustomEvals.csproj" />
+    <Project Path="samples/02-agents/Evaluation/Evaluation_ExpectedOutputs/Evaluation_ExpectedOutputs.csproj" />
+    <Project Path="samples/02-agents/Evaluation/Evaluation_Multimodal/Evaluation_Multimodal.csproj" />
  </Folder>
  <Folder Name="/Samples/02-agents/AgentWithMemory/">
    <File Path="samples/02-agents/AgentWithMemory/README.md" />
@@ -163,6 +183,7 @@
    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj" />
    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj" />
    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj" />
+    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step06_CodeInterpreterFileDownload/Agent_OpenAI_Step06_CodeInterpreterFileDownload.csproj" />
  </Folder>
  <Folder Name="/Samples/02-agents/AgentWithRAG/">
    <File Path="samples/02-agents/AgentWithRAG/README.md" />
@@ -170,6 +191,7 @@
    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/AgentWithRAG_Step02_CustomVectorStoreRAG.csproj" />
    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/AgentWithRAG_Step03_CustomRAGDataSource.csproj" />
    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step04_FoundryServiceRAG/AgentWithRAG_Step04_FoundryServiceRAG.csproj" />
+    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step05_Neo4jGraphRAG/AgentWithRAG_Step05_Neo4jGraphRAG.csproj" />
  </Folder>
  <Folder Name="/Samples/02-agents/ModelContextProtocol/">
    <File Path="samples/02-agents/ModelContextProtocol/README.md" />
@@ -211,12 +233,12 @@
    <Project Path="samples/03-workflows/Declarative/ToolApproval/ToolApproval.csproj" />
  </Folder>
  <Folder Name="/Samples/03-workflows/Declarative/Examples/">
-    <File Path="../workflow-samples/CustomerSupport.yaml" />
-    <File Path="../workflow-samples/DeepResearch.yaml" />
-    <File Path="../workflow-samples/Marketing.yaml" />
-    <File Path="../workflow-samples/MathChat.yaml" />
-    <File Path="../workflow-samples/README.md" />
-    <File Path="../workflow-samples/wttr.json" />
+    <File Path="../declarative-agents/workflow-samples/CustomerSupport.yaml" />
+    <File Path="../declarative-agents/workflow-samples/DeepResearch.yaml" />
+    <File Path="../declarative-agents/workflow-samples/Marketing.yaml" />
+    <File Path="../declarative-agents/workflow-samples/MathChat.yaml" />
+    <File Path="../declarative-agents/workflow-samples/README.md" />
+    <File Path="../declarative-agents/workflow-samples/wttr.json" />
  </Folder>
  <Folder Name="/Samples/03-workflows/SharedStates/">
    <Project Path="samples/03-workflows/SharedStates/SharedStates.csproj" />
@@ -238,6 +260,9 @@
  <Folder Name="/Samples/03-workflows/HumanInTheLoop/">
    <Project Path="samples/03-workflows/HumanInTheLoop/HumanInTheLoopBasic/HumanInTheLoopBasic.csproj" />
  </Folder>
+  <Folder Name="/Samples/03-workflows/Orchestration/">
+    <Project Path="samples/03-workflows/Orchestration/Handoff/Handoff.csproj" />
+  </Folder>
  <Folder Name="/Samples/03-workflows/Observability/">
    <Project Path="samples/03-workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
    <Project Path="samples/03-workflows/Observability/AspireDashboard/AspireDashboard.csproj" />
@@ -255,6 +280,9 @@
    <Project Path="samples/03-workflows/_StartHere/06_MixedWorkflowAgentsAndExecutors/06_MixedWorkflowAgentsAndExecutors.csproj" />
    <Project Path="samples/03-workflows/_StartHere/07_WriterCriticWorkflow/07_WriterCriticWorkflow.csproj" />
  </Folder>
+  <Folder Name="/Samples/03-workflows/Evaluation/">
+    <Project Path="samples/03-workflows/Evaluation/Evaluation_WorkflowEval/Evaluation_WorkflowEval.csproj" />
+  </Folder>
  <Folder Name="/Samples/04-hosting/" />
  <Folder Name="/Samples/04-hosting/DurableAgents/" />
  <Folder Name="/Samples/04-hosting/DurableAgents/AzureFunctions/">
@@ -283,11 +311,16 @@
    <File Path="samples/04-hosting/A2A/README.md" />
    <Project Path="samples/04-hosting/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
    <Project Path="samples/04-hosting/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
-  </Folder>  
+  </Folder>
  <Folder Name="/Samples/05-end-to-end/">
    <Project Path="samples/05-end-to-end/AgentWithPurview/AgentWithPurview.csproj" />
    <Project Path="samples/05-end-to-end/M365Agent/M365Agent.csproj" />
  </Folder>
+  <Folder Name="/Samples/05-end-to-end/Evaluation/">
+    <Project Path="samples/05-end-to-end/Evaluation/Evaluation_FoundryQuality/Evaluation_FoundryQuality.csproj" />
+    <Project Path="samples/05-end-to-end/Evaluation/Evaluation_MixedProviders/Evaluation_MixedProviders.csproj" />
+    <Project Path="samples/05-end-to-end/Evaluation/Evaluation_ConversationSplits/Evaluation_ConversationSplits.csproj" />
+  </Folder>
  <Folder Name="/Samples/05-end-to-end/A2AClientServer/">
    <File Path="samples/05-end-to-end/A2AClientServer/README.md" />
    <Project Path="samples/05-end-to-end/A2AClientServer/A2AClient/A2AClient.csproj" />
@@ -475,13 +508,13 @@
    <Project Path="src/Microsoft.Agents.AI.AGUI/Microsoft.Agents.AI.AGUI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Anthropic/Microsoft.Agents.AI.Anthropic.csproj" />
    <Project Path="src/Microsoft.Agents.AI.AzureAI.Persistent/Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.AzureAI/Microsoft.Agents.AI.AzureAI.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Foundry/Microsoft.Agents.AI.Foundry.csproj" />
    <Project Path="src/Microsoft.Agents.AI.CopilotStudio/Microsoft.Agents.AI.CopilotStudio.csproj" />
    <Project Path="src/Microsoft.Agents.AI.CosmosNoSql/Microsoft.Agents.AI.CosmosNoSql.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj" />
    <Project Path="src/Microsoft.Agents.AI.DevUI/Microsoft.Agents.AI.DevUI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.FoundryMemory/Microsoft.Agents.AI.FoundryMemory.csproj" />
+
    <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />
@@ -492,7 +525,7 @@
    <Project Path="src/Microsoft.Agents.AI.Mem0/Microsoft.Agents.AI.Mem0.csproj" />
    <Project Path="src/Microsoft.Agents.AI.OpenAI/Microsoft.Agents.AI.OpenAI.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.AzureAI/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.Foundry/Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.Mcp/Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
    <Project Path="src/Microsoft.Agents.AI.Workflows.Generators/Microsoft.Agents.AI.Workflows.Generators.csproj" />
@@ -503,11 +536,11 @@
  <Folder Name="/Tests/IntegrationTests/">
    <Project Path="tests/AgentConformance.IntegrationTests/AgentConformance.IntegrationTests.csproj" />
    <Project Path="tests/AnthropicChatCompletion.IntegrationTests/AnthropicChatCompletion.IntegrationTests.csproj" />
-    <Project Path="tests/AzureAI.IntegrationTests/AzureAI.IntegrationTests.csproj" />
+    <Project Path="tests/Foundry.IntegrationTests/Foundry.IntegrationTests.csproj" />
    <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
    <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.IntegrationTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.FoundryMemory.IntegrationTests/Microsoft.Agents.AI.FoundryMemory.IntegrationTests.csproj" />
+
    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests.csproj" />
@@ -518,17 +551,18 @@
    <Project Path="tests/OpenAIResponse.IntegrationTests/OpenAIResponse.IntegrationTests.csproj" />
  </Folder>
  <Folder Name="/Tests/UnitTests/">
+    <Project Path="tests/Aspire.Hosting.AgentFramework.DevUI.UnitTests/Aspire.Hosting.AgentFramework.DevUI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.A2A.UnitTests/Microsoft.Agents.AI.A2A.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Abstractions.UnitTests/Microsoft.Agents.AI.Abstractions.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.AGUI.UnitTests/Microsoft.Agents.AI.AGUI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Anthropic.UnitTests/Microsoft.Agents.AI.Anthropic.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.AzureAI.UnitTests/Microsoft.Agents.AI.AzureAI.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Foundry.UnitTests/Microsoft.Agents.AI.Foundry.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.CosmosNoSql.UnitTests/Microsoft.Agents.AI.CosmosNoSql.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.DurableTask.UnitTests/Microsoft.Agents.AI.DurableTask.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.FoundryMemory.UnitTests/Microsoft.Agents.AI.FoundryMemory.UnitTests.csproj" />
+
    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Microsoft.Agents.AI.Hosting.A2A.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests.csproj" />
@@ -8,13 +8,13 @@
      "src\\Microsoft.Agents.AI.Anthropic\\Microsoft.Agents.AI.Anthropic.csproj",
      "src\\Microsoft.Agents.AI.GitHub.Copilot\\Microsoft.Agents.AI.GitHub.Copilot.csproj",
      "src\\Microsoft.Agents.AI.AzureAI.Persistent\\Microsoft.Agents.AI.AzureAI.Persistent.csproj",
-      "src\\Microsoft.Agents.AI.AzureAI\\Microsoft.Agents.AI.AzureAI.csproj",
+      "src\\Microsoft.Agents.AI.Foundry\\Microsoft.Agents.AI.Foundry.csproj",
      "src\\Microsoft.Agents.AI.CopilotStudio\\Microsoft.Agents.AI.CopilotStudio.csproj",
      "src\\Microsoft.Agents.AI.CosmosNoSql\\Microsoft.Agents.AI.CosmosNoSql.csproj",
      "src\\Microsoft.Agents.AI.Declarative\\Microsoft.Agents.AI.Declarative.csproj",
      "src\\Microsoft.Agents.AI.DevUI\\Microsoft.Agents.AI.DevUI.csproj",
      "src\\Microsoft.Agents.AI.DurableTask\\Microsoft.Agents.AI.DurableTask.csproj",
-      "src\\Microsoft.Agents.AI.FoundryMemory\\Microsoft.Agents.AI.FoundryMemory.csproj",
+
      "src\\Microsoft.Agents.AI.Hosting.A2A.AspNetCore\\Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj",
      "src\\Microsoft.Agents.AI.Hosting.A2A\\Microsoft.Agents.AI.Hosting.A2A.csproj",
      "src\\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore\\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj",
@@ -24,11 +24,12 @@
      "src\\Microsoft.Agents.AI.Mem0\\Microsoft.Agents.AI.Mem0.csproj",
      "src\\Microsoft.Agents.AI.OpenAI\\Microsoft.Agents.AI.OpenAI.csproj",
      "src\\Microsoft.Agents.AI.Purview\\Microsoft.Agents.AI.Purview.csproj",
-      "src\\Microsoft.Agents.AI.Workflows.Declarative.AzureAI\\Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj",
+      "src\\Microsoft.Agents.AI.Workflows.Declarative.Foundry\\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj",
      "src\\Microsoft.Agents.AI.Workflows.Declarative\\Microsoft.Agents.AI.Workflows.Declarative.csproj",
      "src\\Microsoft.Agents.AI.Workflows.Generators\\Microsoft.Agents.AI.Workflows.Generators.csproj",
      "src\\Microsoft.Agents.AI.Workflows\\Microsoft.Agents.AI.Workflows.csproj",
-      "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.csproj"
+      "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.csproj",
+      "src\\Aspire.Hosting.AgentFramework.DevUI\\Aspire.Hosting.AgentFramework.DevUI.csproj"
    ]
  }
 }
@@ -0,0 +1,95 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// Thread-safe console output with sample-name prefixes and colored status.
+/// </summary>
+internal sealed class ConsoleReporter
+{
+    private readonly object _lock = new();
+
+    /// <summary>
+    /// Writes a complete prefixed line atomically to the console.
+    /// </summary>
+    public void WriteLineWithPrefix(string sampleName, string message, ConsoleColor? color = null)
+    {
+        lock (this._lock)
+        {
+            Console.ForegroundColor = ConsoleColor.Cyan;
+            Console.Write($"[{sampleName}] ");
+            if (color.HasValue)
+            {
+                Console.ForegroundColor = color.Value;
+            }
+            else
+            {
+                Console.ResetColor();
+            }
+
+            Console.WriteLine(message);
+            Console.ResetColor();
+        }
+    }
+
+    /// <summary>
+    /// Prints the final summary table and elapsed time to the console.
+    /// </summary>
+    public void PrintSummary(
+        IReadOnlyList<VerificationResult> orderedResults,
+        IReadOnlyList<(string Name, string Reason)> skipped,
+        TimeSpan elapsed)
+    {
+        var passCount = orderedResults.Count(r => r.Passed);
+        var failCount = orderedResults.Count(r => !r.Passed);
+
+        Console.WriteLine();
+        Console.WriteLine(new string('─', 60));
+        Console.ForegroundColor = ConsoleColor.White;
+        Console.WriteLine("SUMMARY");
+        Console.ResetColor();
+
+        foreach (var result in orderedResults)
+        {
+            Console.ForegroundColor = result.Passed ? ConsoleColor.Green : ConsoleColor.Red;
+            Console.Write(result.Passed ? "  ✓ " : "  ✗ ");
+            Console.ResetColor();
+            Console.WriteLine($"{result.SampleName}: {result.Summary}");
+        }
+
+        foreach (var (name, reason) in skipped)
+        {
+            Console.ForegroundColor = ConsoleColor.Yellow;
+            Console.Write("  ○ ");
+            Console.ResetColor();
+            Console.WriteLine($"{name}: Skipped — {reason}");
+        }
+
+        Console.WriteLine();
+        Console.Write("Results: ");
+        Console.ForegroundColor = ConsoleColor.Green;
+        Console.Write($"{passCount} passed");
+        Console.ResetColor();
+
+        if (failCount > 0)
+        {
+            Console.Write(", ");
+            Console.ForegroundColor = ConsoleColor.Red;
+            Console.Write($"{failCount} failed");
+            Console.ResetColor();
+        }
+
+        if (skipped.Count > 0)
+        {
+            Console.Write(", ");
+            Console.ForegroundColor = ConsoleColor.Yellow;
+            Console.Write($"{skipped.Count} skipped");
+            Console.ResetColor();
+        }
+
+        Console.WriteLine();
+        Console.ForegroundColor = ConsoleColor.DarkGray;
+        Console.WriteLine($"Elapsed: {elapsed.Hours:D2}:{elapsed.Minutes:D2}:{elapsed.Seconds:D2}");
+        Console.ResetColor();
+    }
+}
@@ -0,0 +1,56 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+
+namespace VerifySamples;
+
+/// <summary>
+/// Writes a CSV summary of sample verification results.
+/// </summary>
+internal static class CsvResultWriter
+{
+    /// <summary>
+    /// Writes the results to a CSV file at the specified path.
+    /// </summary>
+    public static async Task WriteAsync(
+        string path,
+        IReadOnlyList<VerificationResult> orderedResults,
+        IReadOnlyList<(string Name, string Reason)> skipped,
+        IReadOnlyList<SampleDefinition> samples)
+    {
+        var pathLookup = samples.ToDictionary(s => s.Name, s => s.ProjectPath);
+
+        var sb = new StringBuilder();
+        sb.AppendLine("Sample,ProjectPath,Status,FailedChecks,Failures");
+
+        foreach (var result in orderedResults)
+        {
+            var status = result.Passed ? "PASSED" : "FAILED";
+            var failedChecks = result.Failures.Count;
+            var failures = string.Join("; ", result.Failures);
+            pathLookup.TryGetValue(result.SampleName, out var projectPath);
+            sb.AppendLine($"{CsvEscape(result.SampleName)},{CsvEscape(projectPath ?? "")},{status},{failedChecks},{CsvEscape(failures)}");
+        }
+
+        foreach (var (name, reason) in skipped)
+        {
+            pathLookup.TryGetValue(name, out var projectPath);
+            sb.AppendLine($"{CsvEscape(name)},{CsvEscape(projectPath ?? "")},SKIPPED,0,{CsvEscape(reason)}");
+        }
+
+        await File.WriteAllTextAsync(path, sb.ToString());
+    }
+
+    /// <summary>
+    /// Escapes a value for CSV: wraps in quotes if it contains commas, quotes, or newlines.
+    /// </summary>
+    private static string CsvEscape(string value)
+    {
+        if (value.Contains('"') || value.Contains(',') || value.Contains('\n') || value.Contains('\r'))
+        {
+            return $"\"{value.Replace("\"", "\"\"")}\"";
+        }
+
+        return value;
+    }
+}
@@ -0,0 +1,105 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// Defines the expected behavior for each sample in 01-get-started.
+/// </summary>
+internal static class GetStartedSamples
+{
+    public static IReadOnlyList<SampleDefinition> All { get; } =
+    [
+        new SampleDefinition
+        {
+            Name = "05_first_workflow",
+            ProjectPath = "samples/01-get-started/05_first_workflow",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "UppercaseExecutor: HELLO, WORLD!",
+                "ReverseTextExecutor: !DLROW ,OLLEH",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "01_hello_agent",
+            ProjectPath = "samples/01-get-started/01_hello_agent",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should contain a joke about a pirate.",
+                "There should be two separate joke responses — one from a non-streaming call and one from a streaming call.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "02_add_tools",
+            ProjectPath = "samples/01-get-started/02_add_tools",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            MustContain = [],
+            ExpectedOutputDescription =
+            [
+                "The output should contain information about the weather in Amsterdam.",
+                "The response should mention that it is cloudy with a high of 15°C (or equivalent), since this comes from a tool that returns a canned response.",
+                "There should be two responses — one from a non-streaming call and one from a streaming call.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "03_multi_turn",
+            ProjectPath = "samples/01-get-started/03_multi_turn",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should contain a joke about a pirate.",
+                "After the initial joke, there should be a modified version that includes emojis and is told in the voice of a pirate's parrot.",
+                "The pattern repeats: first a non-streaming pirate joke + parrot version, then a streaming pirate joke + parrot version.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "04_memory",
+            ProjectPath = "samples/01-get-started/04_memory",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            MustContain =
+            [
+                ">> Use session with blank memory",
+                ">> Use deserialized session with previously created memories",
+                ">> Read memories using memory component",
+                "MEMORY - User Name:",
+                "MEMORY - User Age:",
+                ">> Use new session with previously created memories",
+            ],
+            ExpectedOutputDescription =
+            [
+                "In the 'Use session with blank memory' section, the agent should respond to the user's messages. It may ask for the user's name or age if not yet known.",
+                "In the 'Use deserialized session with previously created memories' section, the agent should correctly recall that the user's name is Ruaidhrí and age is 20.",
+                "The 'MEMORY - User Name:' line should show 'Ruaidhrí' (or a close transliteration).",
+                "The 'MEMORY - User Age:' line should show '20'.",
+                "In the 'Use new session with previously created memories' section, the agent should know the user's name and age from the transferred memory.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "06_host_your_agent",
+            ProjectPath = "samples/01-get-started/06_host_your_agent",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            SkipReason = "Requires Azure Functions Core Tools runtime and starts a web server.",
+        },
+    ];
+}
@@ -0,0 +1,153 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+
+namespace VerifySamples;
+
+/// <summary>
+/// Incrementally writes a sequential (non-interleaved) log file, appending after each sample completes.
+/// Thread-safe: multiple parallel tasks may call write methods concurrently.
+/// </summary>
+internal sealed class LogFileWriter : IDisposable
+{
+    private readonly string _path;
+    private readonly SemaphoreSlim _writeLock = new(1, 1);
+
+    public LogFileWriter(string path)
+    {
+        this._path = path;
+    }
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        this._writeLock.Dispose();
+    }
+
+    /// <summary>
+    /// Writes the log file header. Call once at the start of the run.
+    /// </summary>
+    public async Task WriteHeaderAsync()
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine($"Sample Verification Log — {DateTime.UtcNow:yyyy-MM-dd HH:mm:ss} UTC");
+        sb.AppendLine(new string('═', 72));
+        sb.AppendLine();
+
+        await File.WriteAllTextAsync(this._path, sb.ToString());
+    }
+
+    /// <summary>
+    /// Appends a skipped-sample entry to the log file.
+    /// </summary>
+    public async Task WriteSkippedAsync(string name, string reason)
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine($"── {name} ──");
+        sb.AppendLine($"Status: SKIPPED — {reason}");
+        sb.AppendLine();
+
+        await this.AppendAsync(sb.ToString());
+    }
+
+    /// <summary>
+    /// Appends a completed sample's full output section to the log file.
+    /// </summary>
+    public async Task WriteSampleResultAsync(VerificationResult result)
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine(new string('─', 72));
+        sb.AppendLine($"── {result.SampleName} ──");
+        sb.AppendLine($"Status: {(result.Passed ? "PASSED" : "FAILED")}");
+        sb.AppendLine();
+
+        foreach (var line in result.LogLines)
+        {
+            sb.AppendLine(line);
+        }
+
+        sb.AppendLine();
+
+        if (!string.IsNullOrWhiteSpace(result.Stdout))
+        {
+            sb.AppendLine("--- stdout ---");
+            sb.AppendLine(result.Stdout.TrimEnd());
+            sb.AppendLine("--- end stdout ---");
+            sb.AppendLine();
+        }
+
+        if (!string.IsNullOrWhiteSpace(result.Stderr))
+        {
+            sb.AppendLine("--- stderr ---");
+            sb.AppendLine(result.Stderr.TrimEnd());
+            sb.AppendLine("--- end stderr ---");
+            sb.AppendLine();
+        }
+
+        if (result.Failures.Count > 0)
+        {
+            sb.AppendLine("Failures:");
+            foreach (var failure in result.Failures)
+            {
+                sb.AppendLine($"  ✗ {failure}");
+            }
+
+            sb.AppendLine();
+        }
+
+        if (result.AIReasoning is not null)
+        {
+            sb.AppendLine("AI Reasoning:");
+            sb.AppendLine(result.AIReasoning);
+            sb.AppendLine();
+        }
+
+        await this.AppendAsync(sb.ToString());
+    }
+
+    /// <summary>
+    /// Appends the final summary section and elapsed time to the log file.
+    /// </summary>
+    public async Task WriteSummaryAsync(
+        IReadOnlyList<VerificationResult> orderedResults,
+        IReadOnlyList<(string Name, string Reason)> skipped,
+        TimeSpan elapsed)
+    {
+        var passCount = orderedResults.Count(r => r.Passed);
+        var failCount = orderedResults.Count(r => !r.Passed);
+
+        var sb = new StringBuilder();
+        sb.AppendLine(new string('═', 72));
+        sb.AppendLine("SUMMARY");
+        sb.AppendLine();
+
+        foreach (var result in orderedResults)
+        {
+            sb.AppendLine($"  {(result.Passed ? "✓" : "✗")} {result.SampleName}: {result.Summary}");
+        }
+
+        foreach (var (name, reason) in skipped)
+        {
+            sb.AppendLine($"  ○ {name}: Skipped — {reason}");
+        }
+
+        sb.AppendLine();
+        sb.AppendLine($"Results: {passCount} passed{(failCount > 0 ? $", {failCount} failed" : "")}{(skipped.Count > 0 ? $", {skipped.Count} skipped" : "")}");
+        sb.AppendLine($"Elapsed: {elapsed.Hours:D2}:{elapsed.Minutes:D2}:{elapsed.Seconds:D2}");
+
+        await this.AppendAsync(sb.ToString());
+    }
+
+    private async Task AppendAsync(string text)
+    {
+        await this._writeLock.WaitAsync();
+        try
+        {
+            await File.AppendAllTextAsync(this._path, text);
+        }
+        finally
+        {
+            this._writeLock.Release();
+        }
+    }
+}
@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+
+namespace VerifySamples;
+
+/// <summary>
+/// Writes a Markdown summary of sample verification results.
+/// </summary>
+internal static class MarkdownResultWriter
+{
+    /// <summary>
+    /// Writes the results to a Markdown file at the specified path.
+    /// </summary>
+    public static async Task WriteAsync(
+        string path,
+        IReadOnlyList<VerificationResult> orderedResults,
+        IReadOnlyList<(string Name, string Reason)> skipped,
+        TimeSpan elapsed)
+    {
+        var passCount = orderedResults.Count(r => r.Passed);
+        var failCount = orderedResults.Count(r => !r.Passed);
+
+        var sb = new StringBuilder();
+        sb.AppendLine("# Sample Verification Results");
+        sb.AppendLine();
+        sb.AppendLine($"**{passCount} passed, {failCount} failed, {skipped.Count} skipped** | Elapsed: {elapsed.Hours:D2}:{elapsed.Minutes:D2}:{elapsed.Seconds:D2}");
+        sb.AppendLine();
+
+        // Results table
+        sb.AppendLine("| Sample | Status | Failed Checks | Failures |");
+        sb.AppendLine("|--------|--------|---------------|----------|");
+
+        foreach (var result in orderedResults)
+        {
+            var status = result.Passed ? "✅ PASSED" : "❌ FAILED";
+            var failedChecks = result.Failures.Count;
+            var failures = MdEscape(string.Join("; ", result.Failures));
+            sb.AppendLine($"| {MdEscape(result.SampleName)} | {status} | {failedChecks} | {failures} |");
+        }
+
+        foreach (var (name, reason) in skipped)
+        {
+            sb.AppendLine($"| {MdEscape(name)} | ⏭️ SKIPPED | 0 | {MdEscape(reason)} |");
+        }
+
+        // Collapsible AI reasoning details for failures
+        var failures2 = orderedResults.Where(r => !r.Passed && !string.IsNullOrEmpty(r.AIReasoning)).ToList();
+        if (failures2.Count > 0)
+        {
+            sb.AppendLine();
+            sb.AppendLine("## Failure Details");
+            sb.AppendLine();
+
+            foreach (var result in failures2)
+            {
+                sb.AppendLine($"<details><summary><strong>{HtmlEscape(result.SampleName)}</strong></summary>");
+                sb.AppendLine();
+                if (result.Failures.Count > 0)
+                {
+                    foreach (var failure in result.Failures)
+                    {
+                        sb.AppendLine($"- {MdEscape(failure)}");
+                    }
+
+                    sb.AppendLine();
+                }
+
+                sb.AppendLine("**AI Reasoning:**");
+                sb.AppendLine();
+                sb.AppendLine("```");
+                sb.AppendLine(result.AIReasoning);
+                sb.AppendLine("```");
+                sb.AppendLine();
+                sb.AppendLine("</details>");
+                sb.AppendLine();
+            }
+        }
+
+        await File.WriteAllTextAsync(path, sb.ToString());
+    }
+
+    /// <summary>
+    /// Escapes pipe characters and newlines for use inside Markdown table cells.
+    /// </summary>
+    private static string MdEscape(string value)
+    {
+        return value.Replace("|", "\\|").Replace("\n", " ").Replace("\r", "");
+    }
+
+    /// <summary>
+    /// Escapes HTML special characters for use inside HTML tags.
+    /// </summary>
+    private static string HtmlEscape(string value)
+    {
+        return value.Replace("&", "&amp;").Replace("<", "&lt;").Replace(">", "&gt;").Replace("\"", "&quot;");
+    }
+}
@@ -0,0 +1,109 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This tool runs the 01-get-started, 02-agents, and 03-workflows samples and verifies their output.
+// Deterministic samples are verified with exact string matching.
+// Non-deterministic (LLM) samples are verified using an agent-framework agent.
+//
+// Usage:
+//   dotnet run                                          # Run all samples
+//   dotnet run -- 01_hello_agent 05_first_workflow      # Run specific samples by name
+//   dotnet run -- --category 01-get-started             # Run the 01-get-started category
+//   dotnet run -- --category 02-agents                  # Run the 02-agents category
+//   dotnet run -- --category 03-workflows               # Run the 03-workflows category
+//   dotnet run -- --parallel 16                         # Run up to 16 samples concurrently
+//   dotnet run -- --log results.log                     # Write sequential log to file
+//   dotnet run -- --csv results.csv                     # Write CSV summary to file
+//   dotnet run -- --md results.md                       # Write Markdown summary to file
+//   dotnet run -- --build                                # Build samples during run (default: --no-build)
+// Note: By default, this tool expects sample build outputs to already exist.
+// Pre-build the solution before running, or pass --build to avoid missing build output failures.
+//
+// Required environment variables (for AI-powered samples):
+//   AZURE_OPENAI_ENDPOINT
+//   AZURE_OPENAI_DEPLOYMENT_NAME (optional, defaults to gpt-5-mini)
+
+using System.Diagnostics;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using VerifySamples;
+
+var options = VerifyOptions.Parse(args);
+if (options is null)
+{
+    return 1;
+}
+
+var stopwatch = Stopwatch.StartNew();
+
+// Resolve the dotnet/ root directory (verify-samples is at dotnet/eng/verify-samples/)
+var dotnetRoot = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "..", "..", "..", "..", ".."));
+if (!File.Exists(Path.Combine(dotnetRoot, "agent-framework-dotnet.slnx")))
+{
+    dotnetRoot = Path.GetFullPath(Path.Combine(Directory.GetCurrentDirectory(), "..", ".."));
+}
+
+// Set up the AI verifier
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5-mini";
+
+OpenAI.Chat.ChatClient? chatClient = null;
+if (!string.IsNullOrEmpty(endpoint))
+{
+    chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
+        .GetChatClient(deploymentName);
+}
+
+// Set up optional log file writer
+LogFileWriter? logWriter = null;
+if (options.LogFilePath is not null)
+{
+    logWriter = new LogFileWriter(options.LogFilePath);
+    await logWriter.WriteHeaderAsync();
+}
+
+try
+{
+    // Run all samples
+    var reporter = new ConsoleReporter();
+    var verifier = new SampleVerifier(chatClient);
+    var orchestrator = new VerificationOrchestrator(verifier, reporter, dotnetRoot, TimeSpan.FromMinutes(3), logWriter, buildSamples: options.BuildSamples);
+
+    var run = await orchestrator.RunAllAsync(options.Samples, options.MaxParallelism);
+
+    stopwatch.Stop();
+
+    // Print summary
+    var orderedResults = run.SampleOrder
+        .Where(run.Results.ContainsKey)
+        .Select(name => run.Results[name])
+        .ToList();
+
+    reporter.PrintSummary(orderedResults, run.Skipped, stopwatch.Elapsed);
+
+    // Write log file summary
+    if (logWriter is not null)
+    {
+        await logWriter.WriteSummaryAsync(orderedResults, run.Skipped, stopwatch.Elapsed);
+        Console.WriteLine($"Log written to: {options.LogFilePath}");
+    }
+
+    // Write CSV summary
+    if (options.CsvFilePath is not null)
+    {
+        await CsvResultWriter.WriteAsync(options.CsvFilePath, orderedResults, run.Skipped, options.Samples);
+        Console.WriteLine($"CSV written to: {options.CsvFilePath}");
+    }
+
+    // Write Markdown summary
+    if (options.MarkdownFilePath is not null)
+    {
+        await MarkdownResultWriter.WriteAsync(options.MarkdownFilePath, orderedResults, run.Skipped, stopwatch.Elapsed);
+        Console.WriteLine($"Markdown written to: {options.MarkdownFilePath}");
+    }
+
+    return orderedResults.Any(r => !r.Passed) ? 1 : 0;
+}
+finally
+{
+    logWriter?.Dispose();
+}
@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// Describes a sample to verify, including its expected output.
+/// </summary>
+internal sealed class SampleDefinition
+{
+    /// <summary>
+    /// Display name for the sample (e.g., "01_hello_agent").
+    /// </summary>
+    public required string Name { get; init; }
+
+    /// <summary>
+    /// Relative path from the dotnet/ directory to the sample project directory.
+    /// </summary>
+    public required string ProjectPath { get; init; }
+
+    /// <summary>
+    /// Environment variables that the sample requires for a meaningful run.
+    /// The runner checks these before running and will skip the sample if any are unset,
+    /// recording a skip reason that indicates which required variables are missing.
+    /// </summary>
+    public string[] RequiredEnvironmentVariables { get; init; } = [];
+
+    /// <summary>
+    /// Environment variables that the sample can use but typically has fallbacks or defaults for.
+    /// If these are not set, the sample might prompt or behave interactively, which could cause
+    /// automated verification to hang. The runner checks these and skips the sample if they are unset
+    /// to avoid non-deterministic or blocking behavior in automated runs.
+    /// </summary>
+    public string[] OptionalEnvironmentVariables { get; init; } = [];
+
+    /// <summary>
+    /// If set, the sample is skipped with this reason.
+    /// Use only for structural reasons (e.g., web server, multi-process, needs external service).
+    /// Do NOT use for missing environment variables — those are checked dynamically.
+    /// </summary>
+    public string? SkipReason { get; init; }
+
+    /// <summary>
+    /// Substrings that must appear in stdout for the sample to pass.
+    /// Used for deterministic verification.
+    /// </summary>
+    public string[] MustContain { get; init; } = [];
+
+    /// <summary>
+    /// Substrings that must not appear in stdout for the sample to pass.
+    /// </summary>
+    public string[] MustNotContain { get; init; } = [];
+
+    /// <summary>
+    /// If true, <see cref="MustContain"/> entries cover the entire expected output —
+    /// no AI verification is needed.
+    /// </summary>
+    public bool IsDeterministic { get; init; }
+
+    /// <summary>
+    /// Natural-language description of what the sample output should look like.
+    /// Used by the AI verifier for non-deterministic samples.
+    /// Each entry describes one aspect of the expected output that should be verified.
+    /// </summary>
+    public string[] ExpectedOutputDescription { get; init; } = [];
+
+    /// <summary>
+    /// Sequence of stdin inputs to feed to the sample process.
+    /// Each entry is written as a line (followed by newline) to the process stdin.
+    /// A <c>null</c> entry inserts a delay without writing anything.
+    /// Inputs are sent with a short delay between each to allow the process to prompt.
+    /// </summary>
+    public string?[] Inputs { get; init; } = [];
+
+    /// <summary>
+    /// Delay in milliseconds between each input line. Default is 2000ms.
+    /// Increase for samples that need more time between prompts (e.g., LLM calls between inputs).
+    /// </summary>
+    public int InputDelayMs { get; init; } = 2000;
+}
@@ -0,0 +1,141 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+
+namespace VerifySamples;
+
+/// <summary>
+/// Result of running a sample process.
+/// </summary>
+internal sealed record SampleRunResult(
+    string Stdout,
+    string Stderr,
+    int ExitCode,
+    TimeSpan Elapsed);
+
+/// <summary>
+/// Runs a sample project via <c>dotnet run</c> and captures its output.
+/// </summary>
+internal static class SampleRunner
+{
+    /// <summary>
+    /// Runs <c>dotnet run --framework net10.0</c> in the given project directory.
+    /// When <paramref name="build"/> is false (the default), <c>--no-build</c> is passed
+    /// to skip building, assuming the project was pre-built.
+    /// </summary>
+    public static Task<SampleRunResult> RunAsync(
+        string projectPath,
+        TimeSpan timeout,
+        bool build = false,
+        CancellationToken cancellationToken = default)
+        => RunAsync(projectPath, DotnetRunArgs(build), timeout, inputs: null, inputDelayMs: 0, cancellationToken: cancellationToken);
+
+    /// <summary>
+    /// Runs <c>dotnet run --framework net10.0</c> with stdin inputs.
+    /// When <paramref name="build"/> is false (the default), <c>--no-build</c> is passed
+    /// to skip building, assuming the project was pre-built.
+    /// </summary>
+    public static Task<SampleRunResult> RunAsync(
+        string projectPath,
+        TimeSpan timeout,
+        string?[]? inputs,
+        int inputDelayMs = 2000,
+        bool build = false,
+        CancellationToken cancellationToken = default)
+        => RunAsync(projectPath, DotnetRunArgs(build), timeout, inputs, inputDelayMs, cancellationToken);
+
+    private static string DotnetRunArgs(bool build) =>
+        $"run {(build ? "" : "--no-build")} --framework net10.0";
+
+    /// <summary>
+    /// Runs an arbitrary <c>dotnet</c> command in the given working directory.
+    /// </summary>
+    public static async Task<SampleRunResult> RunAsync(
+        string workingDirectory,
+        string dotnetArgs,
+        TimeSpan timeout,
+        string?[]? inputs = null,
+        int inputDelayMs = 0,
+        CancellationToken cancellationToken = default)
+    {
+        var psi = new ProcessStartInfo
+        {
+            FileName = "dotnet",
+            Arguments = dotnetArgs,
+            WorkingDirectory = workingDirectory,
+            RedirectStandardOutput = true,
+            RedirectStandardError = true,
+            RedirectStandardInput = inputs is { Length: > 0 },
+            UseShellExecute = false,
+            CreateNoWindow = true,
+        };
+
+        var sw = Stopwatch.StartNew();
+
+        using var process = new Process { StartInfo = psi };
+        process.Start();
+
+        var stdoutTask = process.StandardOutput.ReadToEndAsync(cancellationToken);
+        var stderrTask = process.StandardError.ReadToEndAsync(cancellationToken);
+
+        // Feed stdin inputs with delays if configured
+        if (inputs is { Length: > 0 })
+        {
+            _ = Task.Run(async () =>
+            {
+                try
+                {
+                    foreach (var input in inputs)
+                    {
+                        await Task.Delay(inputDelayMs, cancellationToken);
+                        if (input is not null)
+                        {
+                            await process.StandardInput.WriteLineAsync(input.AsMemory(), cancellationToken);
+                            await process.StandardInput.FlushAsync(cancellationToken);
+                        }
+                    }
+
+                    process.StandardInput.Close();
+                }
+                catch (Exception ex) when (ex is IOException or ObjectDisposedException or OperationCanceledException)
+                {
+                    // Process may have exited before all inputs were sent
+                }
+            }, cancellationToken);
+        }
+
+        using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+        cts.CancelAfter(timeout);
+
+        try
+        {
+            await process.WaitForExitAsync(cts.Token);
+        }
+        catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
+        {
+            // Timeout — kill the process
+            try
+            {
+                process.Kill(entireProcessTree: true);
+            }
+            catch
+            {
+                // Best effort
+            }
+
+            sw.Stop();
+            return new SampleRunResult(
+                Stdout: await stdoutTask,
+                Stderr: $"TIMEOUT: Sample did not complete within {timeout.TotalSeconds}s.\n{await stderrTask}",
+                ExitCode: -1,
+                Elapsed: sw.Elapsed);
+        }
+
+        sw.Stop();
+        return new SampleRunResult(
+            Stdout: await stdoutTask,
+            Stderr: await stderrTask,
+            ExitCode: process.ExitCode,
+            Elapsed: sw.Elapsed);
+    }
+}
@@ -0,0 +1,229 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json.Serialization;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI.Chat;
+
+namespace VerifySamples;
+
+/// <summary>
+/// Verifies sample output using deterministic checks and an AI agent
+/// for non-deterministic output validation.
+/// </summary>
+internal sealed class SampleVerifier
+{
+    private readonly AIAgent? _verifierAgent;
+
+    /// <summary>
+    /// Creates a verifier. If <paramref name="chatClient"/> is provided,
+    /// AI-based verification is available for non-deterministic samples.
+    /// </summary>
+    public SampleVerifier(ChatClient? chatClient = null)
+    {
+        if (chatClient is not null)
+        {
+            this._verifierAgent = chatClient.AsAIAgent(
+                instructions: """
+                    You are a test output verifier. You will be given:
+                    1. The actual stdout output of a program
+                    2. The stderr output (if any)
+                    3. A list of expectations about what the output should contain or demonstrate
+
+                    Your job is to determine whether the actual output satisfies each expectation.
+                    Be reasonable — the output comes from an LLM so exact wording won't match, but the
+                    semantic intent should be clearly satisfied.
+
+                    In your response, you MUST:
+                    - Always provide ai_reasoning with a brief overall assessment.
+                    - Always provide exactly one entry in expectation_results for each expectation,
+                      in the same order as the input list.
+                    - For each expectation_results entry, echo the expectation text in the expectation
+                      field and explain your assessment in the detail field, citing evidence from the output.
+                    """,
+                name: "OutputVerifier");
+        }
+    }
+
+    /// <summary>
+    /// Verifies the output of a sample run against its definition.
+    /// </summary>
+    public async Task<VerificationResult> VerifyAsync(SampleDefinition sample, SampleRunResult run)
+    {
+        var failures = new List<string>();
+
+        // 1. Exit code check
+        if (run.ExitCode != 0)
+        {
+            failures.Add($"Exit code was {run.ExitCode}, expected 0. Stderr: {Truncate(run.Stderr, 500)}");
+        }
+
+        // 2. Must-contain checks
+        foreach (var expected in sample.MustContain)
+        {
+            if (!run.Stdout.Contains(expected, StringComparison.Ordinal))
+            {
+                failures.Add($"Output missing expected substring: \"{expected}\"");
+            }
+        }
+
+        // 3. Must-not-contain checks
+        foreach (var unexpected in sample.MustNotContain)
+        {
+            if (run.Stdout.Contains(unexpected, StringComparison.Ordinal))
+            {
+                failures.Add($"Output contains unexpected substring: \"{unexpected}\"");
+            }
+        }
+
+        // 4. AI verification for non-deterministic samples
+        string? aiReasoning = null;
+        if (!sample.IsDeterministic && sample.ExpectedOutputDescription.Length > 0)
+        {
+            if (this._verifierAgent is null)
+            {
+                failures.Add("AI verification required but no AI agent configured (missing AZURE_OPENAI_ENDPOINT).");
+            }
+            else
+            {
+                var aiResult = await this.VerifyWithAIAsync(run.Stdout, run.Stderr, sample.ExpectedOutputDescription);
+                aiReasoning = aiResult.Reasoning;
+
+                foreach (var unmet in aiResult.UnmetExpectations)
+                {
+                    failures.Add($"AI expectation not met: {unmet}");
+                }
+            }
+        }
+
+        bool passed = failures.Count == 0;
+        return new VerificationResult
+        {
+            SampleName = sample.Name,
+            Passed = passed,
+            Summary = passed ? "All checks passed" : $"{failures.Count} check(s) failed",
+            Failures = failures,
+            AIReasoning = aiReasoning,
+        };
+    }
+
+    private async Task<(string Reasoning, List<string> UnmetExpectations)> VerifyWithAIAsync(
+        string stdout,
+        string stderr,
+        string[] expectations)
+    {
+        var expectationList = string.Join("\n", expectations.Select((e, i) => $"  {i + 1}. {e}"));
+
+        var stderrSection = string.IsNullOrWhiteSpace(stderr)
+            ? ""
+            : $"""
+
+                Stderr output:
+                ---
+                {Truncate(stderr, 2000)}
+                ---
+                """;
+
+        var prompt = $"""
+            Actual program output:
+            ---
+            {Truncate(stdout, 4000)}
+            ---
+            {stderrSection}
+            Expectations to verify:
+            {expectationList}
+
+            Does the output satisfy all expectations?
+            """;
+
+        try
+        {
+            var response = await this._verifierAgent!.RunAsync<AIVerificationResponse>(prompt);
+            var result = response.Result;
+
+            if (result is null)
+            {
+                return ($"AI verification returned null result. Raw: {response.Text}", ["AI verification returned null result."]);
+            }
+
+            var reasoning = string.IsNullOrWhiteSpace(result.AIReasoning)
+                ? "(no reasoning provided)"
+                : result.AIReasoning;
+
+            // Collect unmet expectations as individual failures
+            var unmet = new List<string>();
+            if (result.ExpectationResults is { Count: > 0 })
+            {
+                foreach (var er in result.ExpectationResults.Where(er => !er.Met))
+                {
+                    var detail = string.IsNullOrWhiteSpace(er.Detail) ? er.Expectation : $"{er.Expectation} — {er.Detail}";
+                    unmet.Add(detail ?? "Unknown expectation");
+                }
+
+                // If the model flagged overall failure but all individual expectations were met,
+                // still treat as failure using the overall reasoning.
+                if (unmet.Count == 0 && !result.Pass)
+                {
+                    unmet.Add(reasoning);
+                }
+            }
+            else if (!result.Pass)
+            {
+                // Fallback: no per-expectation detail but overall pass is false
+                unmet.Add(reasoning);
+            }
+
+            return (reasoning, unmet);
+        }
+        catch (Exception ex)
+        {
+            return ($"AI verification error: {ex.Message}", [$"AI verification error: {ex.Message}"]);
+        }
+    }
+
+    private static string Truncate(string text, int maxLength)
+        => text.Length <= maxLength ? text : text[..maxLength] + "... (truncated)";
+}
+
+/// <summary>
+/// Structured response from the AI verification agent.
+/// </summary>
+[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated by JSON deserialization via RunAsync<T>.")]
+internal sealed class AIVerificationResponse
+{
+    /// <summary>Whether all expectations were met.</summary>
+    [JsonPropertyName("pass")]
+    public bool Pass { get; set; }
+
+    /// <summary>Brief explanation of the overall assessment.</summary>
+    [JsonPropertyName("ai_reasoning")]
+    [Description("Always required. Brief explanation of the overall assessment, covering all expectations.")]
+    public string AIReasoning { get; set; } = string.Empty;
+
+    /// <summary>Per-expectation results.</summary>
+    [JsonPropertyName("expectation_results")]
+    [Description("Always required. One entry per expectation, in the same order as the input list.")]
+    public List<ExpectationResult> ExpectationResults { get; set; } = [];
+}
+
+/// <summary>
+/// Result for an individual expectation check.
+/// </summary>
+[System.Diagnostics.CodeAnalysis.SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated by JSON deserialization via RunAsync<T>.")]
+internal sealed class ExpectationResult
+{
+    /// <summary>The expectation text that was evaluated.</summary>
+    [JsonPropertyName("expectation")]
+    [Description("Echo back the expectation text being evaluated.")]
+    public string Expectation { get; set; } = string.Empty;
+
+    /// <summary>Whether this expectation was met.</summary>
+    [JsonPropertyName("met")]
+    public bool Met { get; set; }
+
+    /// <summary>Detail about how the expectation was or was not met.</summary>
+    [JsonPropertyName("detail")]
+    [Description("Explain how the expectation was or was not met, citing specific evidence from the output.")]
+    public string Detail { get; set; } = string.Empty;
+}
@@ -0,0 +1,200 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Concurrent;
+
+namespace VerifySamples;
+
+/// <summary>
+/// Orchestrates sample verification: filters, runs in parallel, and collects results.
+/// </summary>
+internal sealed class VerificationOrchestrator
+{
+    private readonly SampleVerifier _verifier;
+    private readonly ConsoleReporter _reporter;
+    private readonly LogFileWriter? _logWriter;
+    private readonly string _dotnetRoot;
+    private readonly TimeSpan _timeout;
+    private readonly bool _buildSamples;
+
+    public VerificationOrchestrator(
+        SampleVerifier verifier,
+        ConsoleReporter reporter,
+        string dotnetRoot,
+        TimeSpan timeout,
+        LogFileWriter? logWriter = null,
+        bool buildSamples = false)
+    {
+        this._verifier = verifier;
+        this._reporter = reporter;
+        this._logWriter = logWriter;
+        this._dotnetRoot = dotnetRoot;
+        this._timeout = timeout;
+        this._buildSamples = buildSamples;
+    }
+
+    /// <summary>
+    /// The result of running all samples through the orchestrator.
+    /// </summary>
+    internal sealed record RunAllResult(
+        ConcurrentDictionary<string, VerificationResult> Results,
+        List<(string Name, string Reason)> Skipped,
+        List<string> SampleOrder);
+
+    /// <summary>
+    /// Filters samples, runs the runnable ones in parallel, and returns all results.
+    /// </summary>
+    public async Task<RunAllResult> RunAllAsync(
+        IReadOnlyList<SampleDefinition> samples,
+        int maxParallelism)
+    {
+        var skipped = new List<(string Name, string Reason)>();
+        var runnableSamples = new List<SampleDefinition>();
+        var sampleOrder = new List<string>();
+
+        // Separate samples into skipped and runnable
+        foreach (var sample in samples)
+        {
+            sampleOrder.Add(sample.Name);
+
+            if (sample.SkipReason is not null)
+            {
+                skipped.Add((sample.Name, sample.SkipReason));
+                this._reporter.WriteLineWithPrefix(sample.Name, $"SKIPPED — {sample.SkipReason}", ConsoleColor.Yellow);
+
+                if (this._logWriter is not null)
+                {
+                    await this._logWriter.WriteSkippedAsync(sample.Name, sample.SkipReason);
+                }
+
+                continue;
+            }
+
+            var missingRequired = sample.RequiredEnvironmentVariables
+                .Where(v => string.IsNullOrEmpty(Environment.GetEnvironmentVariable(v)))
+                .ToList();
+
+            var missingOptional = sample.OptionalEnvironmentVariables
+                .Where(v => string.IsNullOrEmpty(Environment.GetEnvironmentVariable(v)))
+                .ToList();
+
+            if (missingRequired.Count > 0 || missingOptional.Count > 0)
+            {
+                var reasons = new List<string>();
+                if (missingRequired.Count > 0)
+                {
+                    reasons.Add($"Missing required: {string.Join(", ", missingRequired)}");
+                }
+
+                if (missingOptional.Count > 0)
+                {
+                    reasons.Add($"Missing optional (would cause console prompt hang): {string.Join(", ", missingOptional)}");
+                }
+
+                var skipReason = string.Join("; ", reasons);
+                skipped.Add((sample.Name, skipReason));
+                this._reporter.WriteLineWithPrefix(sample.Name, $"SKIPPED — {skipReason}", ConsoleColor.Yellow);
+
+                if (this._logWriter is not null)
+                {
+                    await this._logWriter.WriteSkippedAsync(sample.Name, skipReason);
+                }
+
+                continue;
+            }
+
+            runnableSamples.Add(sample);
+        }
+
+        // Run samples in parallel
+        var results = new ConcurrentDictionary<string, VerificationResult>();
+        var semaphore = new SemaphoreSlim(maxParallelism);
+
+        this._reporter.WriteLineWithPrefix(
+            "runner", $"Running {runnableSamples.Count} samples (max {maxParallelism} parallel)...");
+
+        try
+        {
+            var tasks = runnableSamples.Select(sample => this.RunSingleAsync(sample, results, semaphore)).ToArray();
+            await Task.WhenAll(tasks);
+        }
+        finally
+        {
+            semaphore.Dispose();
+        }
+
+        return new RunAllResult(results, skipped, sampleOrder);
+    }
+
+    private async Task RunSingleAsync(
+        SampleDefinition sample,
+        ConcurrentDictionary<string, VerificationResult> results,
+        SemaphoreSlim semaphore)
+    {
+        await semaphore.WaitAsync();
+        try
+        {
+            var log = new List<string>();
+            log.Add($"[{sample.Name}] Running...");
+            this._reporter.WriteLineWithPrefix(sample.Name, "Running...");
+
+            var projectPath = Path.Combine(this._dotnetRoot, sample.ProjectPath);
+            var run = sample.Inputs.Length > 0
+                ? await SampleRunner.RunAsync(projectPath, this._timeout, sample.Inputs, sample.InputDelayMs, build: this._buildSamples)
+                : await SampleRunner.RunAsync(projectPath, this._timeout, build: this._buildSamples);
+
+            log.Add($"[{sample.Name}] Completed ({run.Elapsed.TotalSeconds:F1}s, exit={run.ExitCode})");
+            this._reporter.WriteLineWithPrefix(
+                sample.Name, $"Completed ({run.Elapsed.TotalSeconds:F1}s, exit={run.ExitCode}). Verifying...");
+
+            var result = await this._verifier.VerifyAsync(sample, run);
+
+            if (result.Passed)
+            {
+                log.Add($"[{sample.Name}] PASSED");
+                this._reporter.WriteLineWithPrefix(sample.Name, "PASSED", ConsoleColor.Green);
+            }
+            else
+            {
+                log.Add($"[{sample.Name}] FAILED");
+                this._reporter.WriteLineWithPrefix(sample.Name, "FAILED", ConsoleColor.Red);
+                foreach (var failure in result.Failures)
+                {
+                    log.Add($"[{sample.Name}]   ✗ {failure}");
+                    this._reporter.WriteLineWithPrefix(sample.Name, $"  ✗ {failure}", ConsoleColor.Red);
+                }
+            }
+
+            if (result.AIReasoning is not null)
+            {
+                log.Add($"[{sample.Name}]   AI: {result.AIReasoning}");
+                this._reporter.WriteLineWithPrefix(
+                    sample.Name, $"  AI: {Truncate(result.AIReasoning, 300)}", ConsoleColor.DarkGray);
+            }
+
+            var verificationResult = new VerificationResult
+            {
+                SampleName = result.SampleName,
+                Passed = result.Passed,
+                Summary = result.Summary,
+                Failures = result.Failures,
+                AIReasoning = result.AIReasoning,
+                Stdout = run.Stdout,
+                Stderr = run.Stderr,
+                LogLines = log,
+            };
+            results[sample.Name] = verificationResult;
+
+            if (this._logWriter is not null)
+            {
+                await this._logWriter.WriteSampleResultAsync(verificationResult);
+            }
+        }
+        finally
+        {
+            semaphore.Release();
+        }
+    }
+
+    private static string Truncate(string text, int maxLength)
+        => text.Length <= maxLength ? text : text[..maxLength] + "...";
+}
@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// The result of verifying a single sample.
+/// </summary>
+internal sealed class VerificationResult
+{
+    public required string SampleName { get; init; }
+    public required bool Passed { get; init; }
+    public required string Summary { get; init; }
+    public List<string> Failures { get; init; } = [];
+    public string? AIReasoning { get; init; }
+
+    /// <summary>
+    /// The sample's stdout output, captured for log file output.
+    /// </summary>
+    public string? Stdout { get; init; }
+
+    /// <summary>
+    /// The sample's stderr output, captured for log file output.
+    /// </summary>
+    public string? Stderr { get; init; }
+
+    /// <summary>
+    /// Per-sample log lines, buffered during parallel execution
+    /// and written sequentially to the log file.
+    /// </summary>
+    public List<string> LogLines { get; init; } = [];
+}
@@ -0,0 +1,151 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// Parsed command-line options for the sample verification tool.
+/// </summary>
+internal sealed class VerifyOptions
+{
+    /// <summary>
+    /// Maximum number of samples to run concurrently.
+    /// </summary>
+    public int MaxParallelism { get; init; } = 8;
+
+    /// <summary>
+    /// Path to write a CSV summary file, or <c>null</c> to skip.
+    /// </summary>
+    public string? CsvFilePath { get; init; }
+
+    /// <summary>
+    /// Path to write a Markdown summary file, or <c>null</c> to skip.
+    /// </summary>
+    public string? MarkdownFilePath { get; init; }
+
+    /// <summary>
+    /// Path to write a sequential log file, or <c>null</c> to skip.
+    /// </summary>
+    public string? LogFilePath { get; init; }
+
+    /// <summary>
+    /// When true, samples are built as part of <c>dotnet run</c>.
+    /// When false (the default), <c>--no-build</c> is passed, assuming a prior build step.
+    /// </summary>
+    public bool BuildSamples { get; init; }
+
+    /// <summary>
+    /// The filtered list of samples to process.
+    /// </summary>
+    public required IReadOnlyList<SampleDefinition> Samples { get; init; }
+
+    /// <summary>
+    /// All known sample set registries, keyed by category name.
+    /// </summary>
+    private static readonly Dictionary<string, IReadOnlyList<SampleDefinition>> s_sampleSets =
+        new(StringComparer.OrdinalIgnoreCase)
+        {
+            ["01-get-started"] = GetStartedSamples.All,
+            ["02-agents"] = AgentsSamples.All,
+            ["03-workflows"] = WorkflowSamples.All,
+        };
+
+    /// <summary>
+    /// Parses command-line arguments and resolves the sample list.
+    /// Returns <c>null</c> and writes to stderr if the arguments are invalid.
+    /// </summary>
+    public static VerifyOptions? Parse(string[] args)
+    {
+        var argList = args.ToList();
+
+        var categoryFilter = ExtractArg(argList, "--category");
+        var logFilePath = ExtractArg(argList, "--log");
+        var csvFilePath = ExtractArg(argList, "--csv");
+        var markdownFilePath = ExtractArg(argList, "--md");
+        var buildSamples = ExtractFlag(argList, "--build");
+
+        int maxParallelism = 8;
+        var parallelArg = ExtractArg(argList, "--parallel");
+        if (parallelArg is not null && int.TryParse(parallelArg, out var p) && p > 0)
+        {
+            maxParallelism = p;
+        }
+
+        HashSet<string>? nameFilter = null;
+        if (argList.Count > 0)
+        {
+            nameFilter = argList.ToHashSet(StringComparer.OrdinalIgnoreCase);
+        }
+
+        // Build the sample list
+        IReadOnlyList<SampleDefinition> samples;
+        if (categoryFilter is not null)
+        {
+            if (!s_sampleSets.TryGetValue(categoryFilter, out var categoryList))
+            {
+                Console.Error.WriteLine(
+                    $"Unknown category '{categoryFilter}'. Available: {string.Join(", ", s_sampleSets.Keys)}");
+                return null;
+            }
+
+            samples = categoryList;
+        }
+        else
+        {
+            samples = s_sampleSets.Values.SelectMany(s => s).ToList();
+        }
+
+        if (nameFilter is not null)
+        {
+            samples = samples.Where(s => nameFilter.Contains(s.Name)).ToList();
+        }
+
+        if (samples.Count == 0)
+        {
+            var allNames = s_sampleSets.Values.SelectMany(s => s).Select(s => s.Name);
+            Console.Error.WriteLine($"No matching samples found. Available: {string.Join(", ", allNames)}");
+            return null;
+        }
+
+        return new VerifyOptions
+        {
+            MaxParallelism = maxParallelism,
+            LogFilePath = logFilePath,
+            CsvFilePath = csvFilePath,
+            MarkdownFilePath = markdownFilePath,
+            BuildSamples = buildSamples,
+            Samples = samples,
+        };
+    }
+
+    private static string? ExtractArg(List<string> list, string flag)
+    {
+        var idx = list.IndexOf(flag);
+        if (idx < 0)
+        {
+            return null;
+        }
+
+        if (idx + 1 >= list.Count)
+        {
+            Console.Error.WriteLine($"Missing value for {flag}.");
+            list.RemoveAt(idx);
+            return null;
+        }
+
+        var value = list[idx + 1];
+        list.RemoveRange(idx, 2);
+        return value;
+    }
+
+    private static bool ExtractFlag(List<string> list, string flag)
+    {
+        var idx = list.IndexOf(flag);
+        if (idx < 0)
+        {
+            return false;
+        }
+
+        list.RemoveAt(idx);
+        return true;
+    }
+}
@@ -0,0 +1,525 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace VerifySamples;
+
+/// <summary>
+/// Defines the expected behavior for each sample in 03-workflows.
+/// </summary>
+internal static class WorkflowSamples
+{
+    public static IReadOnlyList<SampleDefinition> All { get; } =
+    [
+        // ───────────────────────────────────────────────────────────────────
+        // _StartHere
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_01_Streaming",
+            ProjectPath = "samples/03-workflows/_StartHere/01_Streaming",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "UppercaseExecutor: HELLO, WORLD!",
+                "ReverseTextExecutor: !DLROW ,OLLEH",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_02_AgentsInWorkflows",
+            ProjectPath = "samples/03-workflows/_StartHere/02_AgentsInWorkflows",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show agent responses from a translation workflow.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_03_AgentWorkflowPatterns",
+            ProjectPath = "samples/03-workflows/_StartHere/03_AgentWorkflowPatterns",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            Inputs = ["sequential"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription =
+            [
+                "The output should show a sequential workflow pattern with multiple agents executing tasks in order.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_04_MultiModelService",
+            ProjectPath = "samples/03-workflows/_StartHere/04_MultiModelService",
+            RequiredEnvironmentVariables = ["BEDROCK_ACCESS_KEY", "BEDROCK_SECRET_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
+            SkipReason = "Requires multiple external provider API keys (Bedrock, Anthropic, OpenAI).",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_05_SubWorkflows",
+            ProjectPath = "samples/03-workflows/_StartHere/05_SubWorkflows",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "=== Sub-Workflow Demonstration ===",
+                "Final Output:",
+                "=== Main Workflow Completed ===",
+                "Sample Complete: Workflows can be composed hierarchically using sub-workflows",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_06_MixedWorkflowAgentsAndExecutors",
+            ProjectPath = "samples/03-workflows/_StartHere/06_MixedWorkflowAgentsAndExecutors",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            Inputs = ["What is 2 plus 2?"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription =
+            [
+                "The output should show agents and executors working together to process a user question.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_StartHere_07_WriterCriticWorkflow",
+            ProjectPath = "samples/03-workflows/_StartHere/07_WriterCriticWorkflow",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            MustContain = ["=== Writer-Critic Iteration Workflow ==="],
+            ExpectedOutputDescription =
+            [
+                "The output should show a writer-critic iteration workflow with writer and critic sections.",
+                "The critic should either approve or request revisions.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Agents
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Agents_CustomAgentExecutors",
+            ProjectPath = "samples/03-workflows/Agents/CustomAgentExecutors",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show custom workflow events including slogan generation and feedback.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Agents_FoundryAgent",
+            ProjectPath = "samples/03-workflows/Agents/FoundryAgent",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            SkipReason = "Requires Azure AI Foundry project endpoint.",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Agents_GroupChatToolApproval",
+            ProjectPath = "samples/03-workflows/Agents/GroupChatToolApproval",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            MustContain = ["Starting group chat workflow for software deployment..."],
+            ExpectedOutputDescription =
+            [
+                "The output should show a group chat workflow with QA and DevOps agents for software deployment.",
+                "There should be approval requests for tool calls.",
+                "The workflow should show interaction between QA and DevOps agents toward deployment.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Agents_WorkflowAsAnAgent",
+            ProjectPath = "samples/03-workflows/Agents/WorkflowAsAnAgent",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            Inputs = ["hello", "exit"],
+            InputDelayMs = 5000,
+            ExpectedOutputDescription =
+            [
+                "The output should show a conversational workflow responding to the user's hello message.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Checkpoint
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Checkpoint_CheckpointAndRehydrate",
+            ProjectPath = "samples/03-workflows/Checkpoint/CheckpointAndRehydrate",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "Workflow completed with result:",
+                "Number of checkpoints created:",
+                "Hydrating a new workflow instance from the 6th checkpoint.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Checkpoint_CheckpointAndResume",
+            ProjectPath = "samples/03-workflows/Checkpoint/CheckpointAndResume",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "Workflow completed with result:",
+                "Number of checkpoints created:",
+                "Restoring from the 6th checkpoint.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Checkpoint_CheckpointWithHumanInTheLoop",
+            ProjectPath = "samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop",
+            RequiredEnvironmentVariables = [],
+            Inputs = ["50", "25", "40", "45", "42", "50", "25", "40", "45", "42"],
+            InputDelayMs = 1000,
+            MustContain = ["found in"],
+            ExpectedOutputDescription =
+            [
+                "The output should show a number guessing game with higher/lower hints that eventually reaches the correct number.",
+                "The output should demonstrate checkpoint save and restore behavior.",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Concurrent
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Concurrent_Concurrent",
+            ProjectPath = "samples/03-workflows/Concurrent/Concurrent",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show results from concurrent agent processing.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Concurrent_MapReduce",
+            ProjectPath = "samples/03-workflows/Concurrent/MapReduce",
+            RequiredEnvironmentVariables = [],
+            MustContain =
+            [
+                "=== RUNNING WORKFLOW ===",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // ConditionalEdges
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_ConditionalEdges_01_EdgeCondition",
+            ProjectPath = "samples/03-workflows/ConditionalEdges/01_EdgeCondition",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show an email being classified as spam or not spam and processed accordingly.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_ConditionalEdges_02_SwitchCase",
+            ProjectPath = "samples/03-workflows/ConditionalEdges/02_SwitchCase",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show an ambiguous email being classified as spam, not spam, or uncertain.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_ConditionalEdges_03_MultiSelection",
+            ProjectPath = "samples/03-workflows/ConditionalEdges/03_MultiSelection",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            ExpectedOutputDescription =
+            [
+                "The output should show an email being classified and potentially routed to multiple handlers.",
+                "The output should not contain error messages or stack traces.",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // HumanInTheLoop
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_HumanInTheLoop_Basic",
+            ProjectPath = "samples/03-workflows/HumanInTheLoop/HumanInTheLoopBasic",
+            RequiredEnvironmentVariables = [],
+            Inputs = ["50", "25", "40", "45", "42"],
+            InputDelayMs = 1000,
+            MustContain = ["found in"],
+            ExpectedOutputDescription =
+            [
+                "The output should show a number guessing game with higher/lower hints that eventually reaches the correct number 42.",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Loop
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Loop",
+            ProjectPath = "samples/03-workflows/Loop",
+            RequiredEnvironmentVariables = [],
+            MustContain = ["Result:"],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // SharedStates
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_SharedStates",
+            ProjectPath = "samples/03-workflows/SharedStates",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "Total Paragraphs:",
+                "Total Words:",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Visualization
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Visualization",
+            ProjectPath = "samples/03-workflows/Visualization",
+            RequiredEnvironmentVariables = [],
+            IsDeterministic = true,
+            MustContain =
+            [
+                "Generating workflow visualization...",
+                "Mermaid string:",
+                "DiGraph string:",
+            ],
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Observability
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Observability_ApplicationInsights",
+            ProjectPath = "samples/03-workflows/Observability/ApplicationInsights",
+            RequiredEnvironmentVariables = ["APPLICATIONINSIGHTS_CONNECTION_STRING"],
+            SkipReason = "Requires Application Insights connection string.",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Observability_AspireDashboard",
+            ProjectPath = "samples/03-workflows/Observability/AspireDashboard",
+            RequiredEnvironmentVariables = [],
+            SkipReason = "Requires Aspire Dashboard / OTLP endpoint.",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Observability_WorkflowAsAnAgent",
+            ProjectPath = "samples/03-workflows/Observability/WorkflowAsAnAgent",
+            RequiredEnvironmentVariables = ["AZURE_OPENAI_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_OPENAI_DEPLOYMENT_NAME"],
+            SkipReason = "Interactive console with ReadLine loop; requires OTLP endpoint.",
+        },
+
+        // ───────────────────────────────────────────────────────────────────
+        // Declarative
+        // ───────────────────────────────────────────────────────────────────
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_ConfirmInput",
+            ProjectPath = "samples/03-workflows/Declarative/ConfirmInput",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            Inputs = ["hello", "hello"],
+            InputDelayMs = 8000,
+            ExpectedOutputDescription = ["The output should show a confirmation prompt and a user response."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_CustomerSupport",
+            ProjectPath = "samples/03-workflows/Declarative/CustomerSupport",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["My laptop won't start"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription = ["The output should show a customer support workflow processing a laptop issue, with agent responses providing troubleshooting or support."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_DeepResearch",
+            ProjectPath = "samples/03-workflows/Declarative/DeepResearch",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            SkipReason = "Requires external weather API (wttr.in).",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_ExecuteCode",
+            ProjectPath = "samples/03-workflows/Declarative/ExecuteCode",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            Inputs = ["What is 12 * 34?"],
+            InputDelayMs = 5000,
+            ExpectedOutputDescription = ["The output should show a declarative workflow executing generated code, processing a math question and producing a result."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_ExecuteWorkflow",
+            ProjectPath = "samples/03-workflows/Declarative/ExecuteWorkflow",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            SkipReason = "Requires a workflow file path as a CLI argument.",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_FunctionTools",
+            ProjectPath = "samples/03-workflows/Declarative/FunctionTools",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["What are today's specials?", "EXIT"],
+            InputDelayMs = 8000,
+            ExpectedOutputDescription = ["The output should show a workflow calling function tools (e.g. a menu plugin) to answer a question about restaurant specials."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_GenerateCode",
+            ProjectPath = "samples/03-workflows/Declarative/GenerateCode",
+            IsDeterministic = true,
+            MustContain = ["WORKFLOW: Parsing", "WORKFLOW: Defined"],
+            ExpectedOutputDescription = ["The output should show a YAML workflow being parsed and C# code being generated from it."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_HostedWorkflow",
+            ProjectPath = "samples/03-workflows/Declarative/HostedWorkflow",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            SkipReason = "Hosts a persistent workflow server that does not exit.",
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_InputArguments",
+            ProjectPath = "samples/03-workflows/Declarative/InputArguments",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["I'd like to visit Seattle", "EXIT"],
+            InputDelayMs = 8000,
+            ExpectedOutputDescription = ["The output should show a workflow capturing location input and providing travel-related information about Seattle."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_InvokeFunctionTool",
+            ProjectPath = "samples/03-workflows/Declarative/InvokeFunctionTool",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["What's the soup of the day?", "EXIT"],
+            InputDelayMs = 8000,
+            ExpectedOutputDescription = ["The output should show a workflow invoking a function tool (e.g. a menu plugin) to answer a question about the soup of the day."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_InvokeMcpTool",
+            ProjectPath = "samples/03-workflows/Declarative/InvokeMcpTool",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["Search for .NET tutorials on Microsoft Learn"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription = ["The output should show a workflow using MCP tools to search Microsoft Learn documentation and provide a summary of results."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_Marketing",
+            ProjectPath = "samples/03-workflows/Declarative/Marketing",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["A smart water bottle that tracks hydration"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription = ["The output should show a marketing workflow generating content about a smart water bottle product."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_StudentTeacher",
+            ProjectPath = "samples/03-workflows/Declarative/StudentTeacher",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["What is 18 + 27?"],
+            InputDelayMs = 3000,
+            ExpectedOutputDescription = ["The output should show a student-teacher workflow where a student asks a math question and a teacher provides the answer."],
+        },
+
+        new SampleDefinition
+        {
+            Name = "Workflow_Declarative_ToolApproval",
+            ProjectPath = "samples/03-workflows/Declarative/ToolApproval",
+            RequiredEnvironmentVariables = ["AZURE_AI_PROJECT_ENDPOINT"],
+            OptionalEnvironmentVariables = ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            Inputs = ["Search for .NET tutorials", "EXIT"],
+            InputDelayMs = 8000,
+            ExpectedOutputDescription = ["The output should show a workflow using an MCP tool with approval to search Microsoft Learn, followed by an exit from the input loop."],
+        },
+    ];
+}
@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <IsPackable>false</IsPackable>
+    <IsAotCompatible>false</IsAotCompatible>
+    <!-- This is a top-level console app; ConfigureAwait is unnecessary -->
+    <NoWarn>$(NoWarn);CA2007</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -1,18 +1,21 @@
 <Project>
  <PropertyGroup>
    <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>1.0.0</VersionPrefix>
-    <RCNumber>4</RCNumber>
+    <VersionPrefix>1.1.0</VersionPrefix>
+    <RCNumber>1</RCNumber>
    <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260311.1</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260311.1</PackageVersion>
-    <GitTag>1.0.0-rc4</GitTag>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260410.1</PackageVersion>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260410.1</PackageVersion>
+    <PackageVersion Condition="'$(IsReleased)' == 'true'">$(VersionPrefix)</PackageVersion>
+    <GitTag>1.1.0</GitTag>

    <Configurations>Debug;Release;Publish</Configurations>
    <IsPackable>true</IsPackable>

    <!-- Package validation. Baseline Version should be the latest version available on NuGet. -->
-    <PackageValidationBaselineVersion>0.0.1</PackageValidationBaselineVersion>
+    <PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
+    <!-- Enable validation for GA packages -->
+    <EnablePackageValidation Condition="'$(IsReleased)' == 'true'">true</EnablePackageValidation>
    <!-- Validate assembly attributes only for Publish builds -->
    <NoWarn Condition="'$(Configuration)' != 'Publish'">$(NoWarn);CP0003</NoWarn>
    <!-- Do not validate reference assemblies -->
@@ -8,7 +8,7 @@ using Microsoft.Agents.AI;
 using OpenAI.Chat;

 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 deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
@@ -11,7 +11,7 @@ using Microsoft.Extensions.AI;
 using OpenAI.Chat;

 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 deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

 [Description("Get the weather for a given location.")]
 static string GetWeather([Description("The location to get the weather for.")] string location)
@@ -8,7 +8,7 @@ using Microsoft.Agents.AI;
 using OpenAI.Chat;

 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 deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
@@ -16,7 +16,7 @@ using OpenAI.Chat;
 using SampleApp;

 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 deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
@@ -8,7 +8,7 @@
 //
 // Environment variables:
 //   AZURE_OPENAI_ENDPOINT
-//   AZURE_OPENAI_DEPLOYMENT_NAME (defaults to "gpt-4o-mini")
+//   AZURE_OPENAI_DEPLOYMENT_NAME (defaults to "gpt-5.4-mini")
 //
 // Run with: func start
 // Then call: POST http://localhost:7071/api/agents/HostedAgent/run
@@ -23,7 +23,7 @@ using OpenAI.Chat;

 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 deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

 // Set up an AI agent following the standard Microsoft Agent Framework pattern.
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
@@ -15,7 +15,7 @@ All samples require the following environment variables:

 ```bash
 export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
-export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"
 ```

 For the client samples, you can optionally set:
@@ -23,7 +23,7 @@ const string SourceName = "OpenTelemetryAspire.ConsoleApp";
 const string ServiceName = "AgentOpenTelemetry";

 // Configure OpenTelemetry for Aspire dashboard
-var otlpEndpoint = Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT") ?? "http://localhost:4318";
+var otlpEndpoint = Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT") ?? "http://localhost:4317";

 var applicationInsightsConnectionString = Environment.GetEnvironmentVariable("APPLICATIONINSIGHTS_CONNECTION_STRING");

@@ -97,7 +97,7 @@ Console.WriteLine("""
    """);

 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT environment variable is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

 // Log application startup
 appLogger.LogInformation("OpenTelemetry Aspire Demo application started");
@@ -34,7 +34,7 @@ graph TD
 Set the following environment variables:
 ```powershell
 $env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
-$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
 ```

 **Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource.
@@ -5,8 +5,8 @@ This sample demonstrates how to create an AIAgent using Anthropic Claude models
 The sample supports three deployment scenarios:

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

 ## Prerequisites

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

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

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

 Set the following environment variables:

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

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

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

 Set the following environment variables:

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

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

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

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

 using Azure.AI.Agents.Persistent;
 using Azure.Identity;
 using Microsoft.Agents.AI;

 var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

 const string JokerName = "Joker";
 const string JokerInstructions = "You are good at telling jokes.";
@@ -13,14 +13,14 @@ Below is a comparison between the classic and new Foundry Agents approaches:
 Before you begin, ensure you have the following prerequisites:

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

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

 Set the following environment variables:

 ```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
-$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Microsoft Foundry resource endpoint
+$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
 ```
@@ -15,7 +15,7 @@
  </ItemGroup>

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

 </Project>
@@ -1,29 +1,29 @@
 // Copyright (c) Microsoft. All rights reserved.

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

 using Azure.AI.Projects;
 using Azure.AI.Projects.Agents;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.AzureAI;
+using Microsoft.Agents.AI.Foundry;

 var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

 const string JokerName = "JokerAgent";

-// Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
+// Get a client to create/retrieve/delete server side agents with Microsoft Foundry Agents.
 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
 // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
 var aiProjectClient = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential());

 // Define the agent you want to create. (Prompt Agent in this case)
-var agentVersionCreationOptions = new AgentVersionCreationOptions(new PromptAgentDefinition(model: deploymentName) { Instructions = "You are good at telling jokes." });
+var agentVersionCreationOptions = new ProjectsAgentVersionCreationOptions(new DeclarativeAgentDefinition(model: deploymentName) { Instructions = "You are good at telling jokes." });
 // Azure.AI.Agents SDK creates and manages agent by name and versions.
 // You can create a server side agent version with the Azure.AI.Agents SDK client below.
-var createdAgentVersion = aiProjectClient.Agents.CreateAgentVersion(agentName: JokerName, options: agentVersionCreationOptions);
+var createdAgentVersion = aiProjectClient.AgentAdministrationClient.CreateAgentVersion(agentName: JokerName, options: agentVersionCreationOptions);

 // Note:
 //      agentVersion.Id = "<agentName>:<versionNumber>",
@@ -34,15 +34,15 @@ var createdAgentVersion = aiProjectClient.Agents.CreateAgentVersion(agentName: J
 FoundryAgent existingJokerAgent = aiProjectClient.AsAIAgent(createdAgentVersion);

 // You can also create another AIAgent version by providing the same name with a different definition.
-AgentVersion newJokerAgentVersion = await aiProjectClient.Agents.CreateAgentVersionAsync(
+ProjectsAgentVersion newJokerAgentVersion = await aiProjectClient.AgentAdministrationClient.CreateAgentVersionAsync(
    JokerName,
-    new AgentVersionCreationOptions(new PromptAgentDefinition(model: deploymentName) { Instructions = "You are extremely hilarious at telling jokes." }));
+    new ProjectsAgentVersionCreationOptions(new DeclarativeAgentDefinition(model: deploymentName) { Instructions = "You are extremely hilarious at telling jokes." }));
 FoundryAgent newJokerAgent = aiProjectClient.AsAIAgent(newJokerAgentVersion);

 // You can also get the AIAgent latest version just providing its name.
-AgentRecord jokerAgentRecord = await aiProjectClient.Agents.GetAgentAsync(JokerName);
+ProjectsAgentRecord jokerAgentRecord = await aiProjectClient.AgentAdministrationClient.GetAgentAsync(JokerName);
 FoundryAgent jokerAgentLatest = aiProjectClient.AsAIAgent(jokerAgentRecord);
-AgentVersion latestAgentVersion = jokerAgentRecord.GetLatestVersion();
+ProjectsAgentVersion latestAgentVersion = jokerAgentRecord.GetLatestVersion();

 // The AIAgent version can be accessed via the GetService method.
 Console.WriteLine($"Latest agent version id: {latestAgentVersion.Id}");
@@ -55,4 +55,4 @@ Console.WriteLine(await jokerAgentLatest.RunAsync("Tell me a joke about a pirate
 Console.WriteLine(await jokerAgentLatest.RunAsync("Now tell me a joke about a cat and a dog using last joke as the anchor.", session));

 // Cleanup by agent name removes both agent versions created.
-aiProjectClient.Agents.DeleteAgent(existingJokerAgent.Name);
+aiProjectClient.AgentAdministrationClient.DeleteAgent(existingJokerAgent.Name);
@@ -13,14 +13,14 @@ Below is a comparison between the classic and new Foundry Agents approaches:
 Before you begin, ensure you have the following prerequisites:

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

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

 Set the following environment variables:

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

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

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

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

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

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

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

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

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

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

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

 Set the following environment variables:

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

 # Optional, defaults to using Azure CLI for authentication if not provided
@@ -8,7 +8,7 @@ using Microsoft.Agents.AI;
 using OpenAI.Chat;

 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 deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
@@ -12,5 +12,5 @@ Set the following environment variables:

 ```powershell
 $env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" # Replace with your Azure OpenAI resource endpoint
-$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
 ```
@@ -9,7 +9,7 @@ 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 deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

 // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
 // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
@@ -12,5 +12,5 @@ Set the following environment variables:

 ```powershell
 $env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" # Replace with your Azure OpenAI resource endpoint
-$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
 ```
@@ -1,41 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to create and use a simple AI agent with OpenAI Assistants as the backend.
-
-// WARNING: The Assistants API is deprecated and will be shut down.
-// For more information see the OpenAI documentation: https://platform.openai.com/docs/assistants/migration
-
-#pragma warning disable CS0618 // Type or member is obsolete - OpenAI Assistants API is deprecated but still used in this sample
-
-using Microsoft.Agents.AI;
-using OpenAI;
-using OpenAI.Assistants;
-
-var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
-var model = Environment.GetEnvironmentVariable("OPENAI_CHAT_MODEL_NAME") ?? "gpt-4o-mini";
-
-const string JokerName = "Joker";
-const string JokerInstructions = "You are good at telling jokes.";
-
-// Get a client to create/retrieve server side agents with.
-var assistantClient = new OpenAIClient(apiKey).GetAssistantClient();
-
-// You can create a server side assistant with the OpenAI SDK.
-var createResult = await assistantClient.CreateAssistantAsync(model, new() { Name = JokerName, Instructions = JokerInstructions });
-
-// You can retrieve an already created server side assistant as an AIAgent.
-AIAgent agent1 = await assistantClient.GetAIAgentAsync(createResult.Value.Id);
-
-// You can also create a server side assistant and return it as an AIAgent directly.
-AIAgent agent2 = await assistantClient.CreateAIAgentAsync(
-    model: model,
-    name: JokerName,
-    instructions: JokerInstructions);
-
-// You can invoke the agent like any other AIAgent.
-AgentSession session = await agent1.CreateSessionAsync();
-Console.WriteLine(await agent1.RunAsync("Tell me a joke about a pirate.", session));
-
-// Cleanup for sample purposes.
-await assistantClient.DeleteAssistantAsync(agent1.Id);
-await assistantClient.DeleteAssistantAsync(agent2.Id);
@@ -1,16 +0,0 @@
-# Prerequisites
-
-WARNING: The Assistants API is deprecated and will be shut down.
-For more information see the OpenAI documentation: https://platform.openai.com/docs/assistants/migration
-
-Before you begin, ensure you have the following prerequisites:
-
- .NET 10 SDK or later
- OpenAI API key
-
-Set the following environment variables:
-
-```powershell
-$env:OPENAI_API_KEY="*****" # Replace with your OpenAI API key
-$env:OPENAI_CHAT_MODEL_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
-```
@@ -8,7 +8,7 @@ using OpenAI;
 using OpenAI.Chat;

 var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
-var model = Environment.GetEnvironmentVariable("OPENAI_CHAT_MODEL_NAME") ?? "gpt-4o-mini";
+var model = Environment.GetEnvironmentVariable("OPENAI_CHAT_MODEL_NAME") ?? "gpt-5.4-mini";

 AIAgent agent = new OpenAIClient(
    apiKey)
@@ -9,5 +9,5 @@ Set the following environment variables:

 ```powershell
 $env:OPENAI_API_KEY="*****" # Replace with your OpenAI api key
-$env:OPENAI_CHAT_MODEL_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+$env:OPENAI_CHAT_MODEL_NAME="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
 ```
@@ -7,7 +7,7 @@ using OpenAI;
 using OpenAI.Responses;

 var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY") ?? throw new InvalidOperationException("OPENAI_API_KEY is not set.");
-var model = Environment.GetEnvironmentVariable("OPENAI_CHAT_MODEL_NAME") ?? "gpt-4o-mini";
+var model = Environment.GetEnvironmentVariable("OPENAI_CHAT_MODEL_NAME") ?? "gpt-5.4-mini";

 AIAgent agent = new OpenAIClient(
    apiKey)
@@ -9,5 +9,5 @@ Set the following environment variables:

 ```powershell
 $env:OPENAI_API_KEY="*****" # Replace with your OpenAI api key
-$env:OPENAI_CHAT_MODEL_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
+$env:OPENAI_CHAT_MODEL_NAME="gpt-5.4-mini"  # Optional, defaults to gpt-5.4-mini
 ```
@@ -18,14 +18,13 @@ See the README.md for each sample for the prerequisites for that sample.
 |[Creating an AIAgent with Anthropic](./Agent_With_Anthropic/)|This sample demonstrates how to create an AIAgent using Anthropic Claude models as the underlying inference service|
 |[Creating an AIAgent with Foundry Agents using Azure.AI.Agents.Persistent](./Agent_With_AzureAIAgentsPersistent/)|This sample demonstrates how to create a Foundry Persistent agent and expose it as an AIAgent using the Azure.AI.Agents.Persistent SDK|
 |[Creating an AIAgent with Foundry Agents using Azure.AI.Project](./Agent_With_AzureAIProject/)|This sample demonstrates how to create an Foundry Project agent and expose it as an AIAgent using the Azure.AI.Project SDK|
-|[Creating an AIAgent with AzureFoundry Model](./Agent_With_AzureFoundryModel/)|This sample demonstrates how to use any model deployed to Azure Foundry to create an AIAgent|
+|[Creating an AIAgent with Foundry Model](./Agent_With_AzureFoundryModel/)|This sample demonstrates how to use any model deployed to Microsoft Foundry to create an AIAgent|
 |[Creating an AIAgent with Azure OpenAI ChatCompletion](./Agent_With_AzureOpenAIChatCompletion/)|This sample demonstrates how to create an AIAgent using Azure OpenAI ChatCompletion as the underlying inference service|
 |[Creating an AIAgent with Azure OpenAI Responses](./Agent_With_AzureOpenAIResponses/)|This sample demonstrates how to create an AIAgent using Azure OpenAI Responses as the underlying inference service|
 |[Creating an AIAgent with a custom implementation](./Agent_With_CustomImplementation/)|This sample demonstrates how to create an AIAgent with a custom implementation|
 |[Creating an AIAgent with GitHub Copilot](./Agent_With_GitHubCopilot/)|This sample demonstrates how to create an AIAgent using GitHub Copilot SDK as the underlying inference service|
 |[Creating an AIAgent with Ollama](./Agent_With_Ollama/)|This sample demonstrates how to create an AIAgent using Ollama as the underlying inference service|
 |[Creating an AIAgent with ONNX](./Agent_With_ONNX/)|This sample demonstrates how to create an AIAgent using ONNX as the underlying inference service|
-|[Creating an AIAgent with OpenAI Assistants](./Agent_With_OpenAIAssistants/)|This sample demonstrates how to create an AIAgent using OpenAI Assistants as the underlying inference service.</br>WARNING: The Assistants API is deprecated and will be shut down. For more information see the OpenAI documentation: https://platform.openai.com/docs/assistants/migration|
 |[Creating an AIAgent with OpenAI ChatCompletion](./Agent_With_OpenAIChatCompletion/)|This sample demonstrates how to create an AIAgent using OpenAI ChatCompletion as the underlying inference service|
 |[Creating an AIAgent with OpenAI Responses](./Agent_With_OpenAIResponses/)|This sample demonstrates how to create an AIAgent using OpenAI Responses as the underlying inference service|

@@ -16,7 +16,7 @@ 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";
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";

 // --- Skills Provider ---
 // Discovers skills from the 'skills' directory containing SKILL.md files.
@@ -6,7 +6,7 @@ This sample demonstrates how to use **file-based Agent Skills** with a `ChatClie

 - 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
+- Using the `AgentSkillsProvider` constructor with a skill directory path and script runner
 - Running file-based scripts (Python) via a subprocess-based executor

 ## Skills Included
@@ -30,7 +30,7 @@ Converts between common units (miles↔km, pounds↔kg) using a multiplication f

 ```bash
 export AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"
-export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"
 ```

 ### Run
@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);MAAI001</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,90 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to define Agent Skills entirely in code using AgentInlineSkill.
+// No SKILL.md files are needed — skills, resources, and scripts are all defined programmatically.
+//
+// Three approaches are shown using a unit-converter skill:
+// 1. Static resources — inline content provided via AddResource
+// 2. Dynamic resources — computed at runtime via a factory delegate
+// 3. Code scripts — executable delegates the agent can invoke directly
+
+using System.Text.Json;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI.Responses;
+
+// --- Configuration ---
+string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+
+// --- Build the code-defined skill ---
+var unitConverterSkill = new AgentInlineSkill(
+    name: "unit-converter",
+    description: "Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms.",
+    instructions: """
+        Use this skill when the user asks to convert between units.
+
+        1. Review the conversion-table resource to find the factor for the requested conversion.
+        2. Check the conversion-policy resource for rounding and formatting rules.
+        3. Use the convert script, passing the value and factor from the table.
+        """)
+    // 1. Static Resource: conversion tables
+    .AddResource(
+        "conversion-table",
+        """
+        # Conversion Tables
+
+        Formula: **result = value × factor**
+
+        | From        | To          | Factor   |
+        |-------------|-------------|----------|
+        | miles       | kilometers  | 1.60934  |
+        | kilometers  | miles       | 0.621371 |
+        | pounds      | kilograms   | 0.453592 |
+        | kilograms   | pounds      | 2.20462  |
+        """)
+    // 2. Dynamic Resource: conversion policy (computed at runtime)
+    .AddResource("conversion-policy", () =>
+    {
+        const int Precision = 4;
+        return $"""
+            # Conversion Policy
+
+            **Decimal places:** {Precision}
+            **Format:** Always show both the original and converted values with units
+            **Generated at:** {DateTime.UtcNow:O}
+            """;
+    })
+    // 3. Code Script: convert
+    .AddScript("convert", (double value, double factor) =>
+    {
+        double result = Math.Round(value * factor, 4);
+        return JsonSerializer.Serialize(new { value, factor, result });
+    });
+
+// --- Skills Provider ---
+var skillsProvider = new AgentSkillsProvider(unitConverterSkill);
+
+// --- Agent Setup ---
+AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
+    .GetResponsesClient()
+    .AsAIAgent(new ChatClientAgentOptions
+    {
+        Name = "UnitConverterAgent",
+        ChatOptions = new()
+        {
+            Instructions = "You are a helpful assistant that can convert units.",
+        },
+        AIContextProviders = [skillsProvider],
+    },
+    model: deploymentName);
+
+// --- Example: Unit conversion ---
+Console.WriteLine("Converting units with code-defined skills");
+Console.WriteLine(new string('-', 60));
+
+AgentResponse response = await agent.RunAsync(
+    "How many kilometers is a marathon (26.2 miles)? And how many pounds is 75 kilograms?");
+
+Console.WriteLine($"Agent: {response.Text}");
@@ -0,0 +1,52 @@
+# Code-Defined Agent Skills Sample
+
+This sample demonstrates how to define **Agent Skills entirely in code** using `AgentInlineSkill`.
+
+## What it demonstrates
+
+- Creating skills programmatically with `AgentInlineSkill` — no SKILL.md files needed
+- **Static resources** via `AddResource` with inline content
+- **Dynamic resources** via `AddResource` with a factory delegate (computed at runtime)
+- **Code scripts** via `AddScript` with a delegate handler
+- Using the `AgentSkillsProvider` constructor with inline skills
+
+## Skills Included
+
+### unit-converter (code-defined)
+
+Converts between common units using multiplication factors. Defined entirely in C# code:
+
+- `conversion-table` — Static resource with factor table
+- `conversion-policy` — Dynamic resource with formatting rules (generated at runtime)
+- `convert` — Script that performs `value × factor` conversion
+
+## Running the Sample
+
+### Prerequisites
+
+- .NET 10.0 SDK
+- Azure OpenAI endpoint with a deployed model
+
+### Setup
+
+```bash
+export AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"
+export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"
+```
+
+### Run
+
+```bash
+dotnet run
+```
+
+### Expected Output
+
+```
+Converting units with code-defined skills
+------------------------------------------------------------
+Agent: Here are your conversions:
+
+1. **26.2 miles → 42.16 km** (a marathon distance)
+2. **75 kg → 165.35 lbs**
+```
@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);MAAI001;IDE0051</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,111 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to define Agent Skills as C# classes using AgentClassSkill
+// with attributes for automatic script and resource discovery.
+
+using System.ComponentModel;
+using System.Text.Json;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI.Responses;
+
+// --- Configuration ---
+string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5.4-mini";
+
+// --- Class-Based Skill ---
+// Instantiate the skill class.
+var unitConverter = new UnitConverterSkill();
+
+// --- Skills Provider ---
+var skillsProvider = new AgentSkillsProvider(unitConverter);
+
+// --- 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 class-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}");
+
+/// <summary>
+/// A unit-converter skill defined as a C# class using attributes for discovery.
+/// </summary>
+/// <remarks>
+/// Properties annotated with <see cref="AgentSkillResourceAttribute"/> are automatically
+/// discovered as skill resources, and methods annotated with <see cref="AgentSkillScriptAttribute"/>
+/// are automatically discovered as skill scripts. Alternatively,
+/// <see cref="AgentSkill.Resources"/> and <see cref="AgentSkill.Scripts"/> can be overridden.
+/// </remarks>
+internal sealed class UnitConverterSkill : AgentClassSkill<UnitConverterSkill>
+{
+    /// <inheritdoc/>
+    public override AgentSkillFrontmatter Frontmatter { get; } = new(
+        "unit-converter",
+        "Convert between common units using a multiplication factor. Use when asked to convert miles, kilometers, pounds, or kilograms.");
+
+    /// <inheritdoc/>
+    protected override string Instructions => """
+        Use this skill when the user asks to convert between units.
+
+        1. Review the conversion-table resource to find the factor for the requested conversion.
+        2. Use the convert script, passing the value and factor from the table.
+        3. Present the result clearly with both units.
+        """;
+
+    /// <summary>
+    /// Gets the <see cref="JsonSerializerOptions"/> used to marshal parameters and return values
+    /// for scripts and resources.
+    /// </summary>
+    /// <remarks>
+    /// This override is not necessary for this sample, but can be used to provide custom
+    /// serialization options, for example a source-generated <c>JsonTypeInfoResolver</c>
+    /// for Native AOT compatibility.
+    /// </remarks>
+    protected override JsonSerializerOptions? SerializerOptions => null;
+
+    /// <summary>
+    /// A conversion table resource providing multiplication factors.
+    /// </summary>
+    [AgentSkillResource("conversion-table")]
+    [Description("Lookup table of multiplication factors for common unit conversions.")]
+    public string ConversionTable => """
+        # 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  |
+        """;
+
+    /// <summary>
+    /// Converts a value by the given factor.
+    /// </summary>
+    [AgentSkillScript("convert")]
+    [Description("Multiplies a value by a conversion factor and returns the result as JSON.")]
+    private static string ConvertUnits(double value, double factor)
+    {
+        double result = Math.Round(value * factor, 4);
+        return JsonSerializer.Serialize(new { value, factor, result });
+    }
+}
@@ -0,0 +1,53 @@
+# Class-Based Agent Skills Sample
+
+This sample demonstrates how to define **Agent Skills as C# classes** using `AgentClassSkill`
+with **attributes** for automatic script and resource discovery.
+
+## What it demonstrates
+
+- Creating skills as classes that extend `AgentClassSkill`
+- Using `[AgentSkillResource]` on properties to define resources
+- Using `[AgentSkillScript]` on methods to define scripts
+- Automatic discovery (no need to override `Resources`/`Scripts`)
+- Using the `AgentSkillsProvider` constructor with class-based skills
+- Overriding `SerializerOptions` for Native AOT compatibility
+
+## Skills Included
+
+### unit-converter (class-based)
+
+A `UnitConverterSkill` class that converts between common units. Defined in `Program.cs`:
+
+- `conversion-table` — Static resource with factor table
+- `convert` — Script that performs `value × factor` conversion
+
+## Running the Sample
+
+### Prerequisites
+
+- .NET 10.0 SDK
+- Azure OpenAI endpoint with a deployed model
+
+### Setup
+
+```bash
+export AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"
+export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5.4-mini"
+```
+
+### Run
+
+```bash
+dotnet run
+```
+
+### Expected Output
+
+```
+Converting units with class-based skills
+------------------------------------------------------------
+Agent: Here are your conversions:
+
+1. **26.2 miles → 42.16 km** (a marathon distance)
+2. **75 kg → 165.35 lbs**
+```
@@ -0,0 +1,32 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <NoWarn>$(NoWarn);MAAI001;IDE0051</NoWarn>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <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>
+
+  <!-- Copy skills directory to output -->
+  <ItemGroup>
+    <None Include="skills\**\*.*">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>
--- a/Show More
+++ b/Show More