Fixed CA1873 warning (#4479 )

Update package versions (#4468 )
.NET: Discover skill resources from directory instead of markdown links (#4401 )
2026-06-16 21:04:09 +08:00 · 2026-03-04 13:24:53 -08:00 · 2026-03-04 19:11:30 +00:00 · 2026-03-04 18:37:11 +00:00 · 2026-03-04 18:36:02 +00:00 · 2026-03-04 17:05:15 +00:00
1254 changed files with 51975 additions and 8267 deletions
@@ -1,10 +1,6 @@
 {
  "name": "C# (.NET)",
-  //"image": "mcr.microsoft.com/devcontainers/dotnet",
-  // Workaround for https://github.com/devcontainers/images/issues/1752
-  "build": {
-    "dockerfile": "dotnet.Dockerfile"
-  },
+  "image": "mcr.microsoft.com/devcontainers/dotnet",
  "features": {
    "ghcr.io/devcontainers/features/azure-cli:1.2.9": {},
    "ghcr.io/devcontainers/features/github-cli:1": {
@@ -1,5 +0,0 @@
-FROM mcr.microsoft.com/devcontainers/universal:latest
-
-# Remove Yarn repository with expired GPG key to prevent apt-get update failures
-# Tracking issue: https://github.com/devcontainers/images/issues/1752
-RUN rm -f /etc/apt/sources.list.d/yarn.list
@@ -0,0 +1,48 @@
+name: Sample Validation Setup
+description: Sets up the environment for sample validation (checkout, Node.js, Copilot CLI, Azure login, Python)
+
+inputs:
+  azure-client-id:
+    description: Azure Client ID for OIDC login
+    required: true
+  azure-tenant-id:
+    description: Azure Tenant ID for OIDC login
+    required: true
+  azure-subscription-id:
+    description: Azure Subscription ID for OIDC login
+    required: true
+  python-version:
+    description: The Python version to set up
+    required: false
+    default: "3.12"
+  os:
+    description: The operating system to set up
+    required: false
+    default: "Linux"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Set up Node.js environment
+      uses: actions/setup-node@v4
+
+    - name: Install Copilot CLI
+      shell: bash
+      run: npm install -g @github/copilot
+
+    - name: Test Copilot CLI
+      shell: bash
+      run: copilot -p "What can you do in one sentence?"
+
+    - name: Azure CLI Login
+      uses: azure/login@v2
+      with:
+        client-id: ${{ inputs.azure-client-id }}
+        tenant-id: ${{ inputs.azure-tenant-id }}
+        subscription-id: ${{ inputs.azure-subscription-id }}
+
+    - name: Set up python and install the project
+      uses: ./.github/actions/python-setup
+      with:
+        python-version: ${{ inputs.python-version }}
+        os: ${{ inputs.os }}
@@ -23,7 +23,7 @@ workflows:
  - any-glob-to-any-file:
    - dotnet/src/Microsoft.Agents.AI.Workflows/**
    - dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/**
-    - dotnet/samples/GettingStarted/Workflow/**
+    - dotnet/samples/03-workflows/**
    - python/packages/main/agent_framework/_workflow/**
    - python/samples/getting_started/workflow/**

@@ -92,7 +92,7 @@ jobs:
          Write-Host "Launching Azure Cosmos DB Emulator"
          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
          Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
+          echo "COSMOSDB_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV

      - name: Setup dotnet
        uses: actions/setup-dotnet@v5.1.0
@@ -205,20 +205,17 @@ jobs:
          COSMOSDB_ENDPOINT: https://localhost:8081
          COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
          # OpenAI Models
-          OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
-          OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
-          OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}
+          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_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+          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
-          AzureAI__Endpoint: ${{ secrets.AZUREAI__ENDPOINT }}
-          AzureAI__DeploymentName: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
-          AzureAI__BingConnectionId: ${{ vars.AZUREAI__BINGCONECTIONID }}
-          FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-          FOUNDRY_MEDIA_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MEDIA_DEPLOYMENT_NAME }}
-          FOUNDRY_MODEL_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MODEL_DEPLOYMENT_NAME }}
-          FOUNDRY_CONNECTION_GROUNDING_TOOL: ${{ vars.FOUNDRY_CONNECTION_GROUNDING_TOOL }}
+          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 }}

      # Generate test reports and check coverage
      - name: Generate test reports
@@ -0,0 +1,102 @@
+#
+# Dedicated .NET integration tests workflow, called from the manual integration test orchestrator.
+# Only runs integration test matrix entries (net10.0 and net472).
+#
+
+name: dotnet-integration-tests
+
+on:
+  workflow_call:
+    inputs:
+      checkout-ref:
+        description: "Git ref to checkout (e.g., refs/pull/123/head)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  dotnet-integration-tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { targetFramework: "net10.0", os: "ubuntu-latest", configuration: Release }
+          - { targetFramework: "net472", os: "windows-latest", configuration: Release }
+    runs-on: ${{ matrix.os }}
+    environment: integration
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+          sparse-checkout: |
+            .
+            .github
+            dotnet
+            python
+            workflow-samples
+
+      - name: Start Azure Cosmos DB Emulator
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          Write-Host "Launching Azure Cosmos DB Emulator"
+          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
+          Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
+          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
+
+      - name: Setup dotnet
+        uses: actions/setup-dotnet@v5.1.0
+        with:
+          global-json-file: ${{ github.workspace }}/dotnet/global.json
+
+      - name: Build dotnet solutions
+        shell: bash
+        run: |
+          export SOLUTIONS=$(find ./dotnet/ -type f -name "*.slnx" | tr '\n' ' ')
+          for solution in $SOLUTIONS; do
+            dotnet build $solution -c ${{ matrix.configuration }} --warnaserror
+          done
+
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+      - name: Set up Durable Task and Azure Functions Integration Test Emulators
+        if: matrix.os == 'ubuntu-latest'
+        uses: ./.github/actions/azure-functions-integration-setup
+
+      - name: Run Integration Tests
+        shell: bash
+        run: |
+          export INTEGRATION_TEST_PROJECTS=$(find ./dotnet -type f -name "*IntegrationTests.csproj" | tr '\n' ' ')
+          for project in $INTEGRATION_TEST_PROJECTS; do
+            target_frameworks=$(dotnet msbuild $project -getProperty:TargetFrameworks -p:Configuration=${{ matrix.configuration }} -nologo 2>/dev/null | tr -d '\r')
+            if [[ "$target_frameworks" == *"${{ matrix.targetFramework }}"* ]]; then
+              dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx --filter "Category!=IntegrationDisabled"
+            else
+              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
+            fi
+          done
+        env:
+          COSMOSDB_ENDPOINT: https://localhost:8081
+          COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
+          OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
+          OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
+          OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}
+          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+          AzureAI__Endpoint: ${{ secrets.AZUREAI__ENDPOINT }}
+          AzureAI__DeploymentName: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
+          AzureAI__BingConnectionId: ${{ vars.AZUREAI__BINGCONECTIONID }}
+          FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
+          FOUNDRY_MEDIA_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MEDIA_DEPLOYMENT_NAME }}
+          FOUNDRY_MODEL_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MODEL_DEPLOYMENT_NAME }}
+          FOUNDRY_CONNECTION_GROUNDING_TOOL: ${{ vars.FOUNDRY_CONNECTION_GROUNDING_TOOL }}
@@ -0,0 +1,134 @@
+#
+# This workflow allows manually running integration tests against an open PR or a branch.
+# Go to Actions → "Integration Tests (Manual)" → Run workflow → enter a PR number or branch name.
+#
+# It calls dedicated integration-only workflows (dotnet-integration-tests and python-integration-tests),
+# passing a ref so they check out and test the correct code.
+# Changed paths are detected here so only the relevant test suites run.
+#
+
+name: Integration Tests (Manual)
+
+on:
+  workflow_dispatch:
+    inputs:
+      pr-number:
+        description: "PR number to run integration tests against (leave empty if using branch)"
+        required: false
+        type: string
+        default: ""
+      branch:
+        description: "Branch name to run integration tests against (leave empty if using PR number)"
+        required: false
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+  pull-requests: read
+  id-token: write
+
+concurrency:
+  group: integration-tests-manual-${{ github.event.inputs.pr-number || github.event.inputs.branch }}
+  cancel-in-progress: true
+
+jobs:
+  resolve-ref:
+    name: Resolve ref
+    runs-on: ubuntu-latest
+    outputs:
+      checkout-ref: ${{ steps.resolve.outputs.checkout-ref }}
+      dotnet-changes: ${{ steps.detect-changes.outputs.dotnet }}
+      python-changes: ${{ steps.detect-changes.outputs.python }}
+    steps:
+      - name: Resolve checkout ref
+        id: resolve
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.inputs.pr-number }}
+          BRANCH: ${{ github.event.inputs.branch }}
+          REPO: ${{ github.repository }}
+        run: |
+          if [ -n "$PR_NUMBER" ] && [ -n "$BRANCH" ]; then
+            echo "::error::Please provide either a PR number or a branch name, not both."
+            exit 1
+          fi
+
+          if [ -z "$PR_NUMBER" ] && [ -z "$BRANCH" ]; then
+            echo "::error::Please provide either a PR number or a branch name."
+            exit 1
+          fi
+
+          if [ -n "$PR_NUMBER" ]; then
+            if ! echo "$PR_NUMBER" | grep -Eq '^[0-9]+$'; then
+              echo "::error::Invalid PR number. Only numeric values are allowed."
+              exit 1
+            fi
+
+            PR_DATA=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json state)
+            PR_STATE=$(echo "$PR_DATA" | jq -r '.state')
+
+            if [ "$PR_STATE" != "OPEN" ]; then
+              echo "::error::PR #$PR_NUMBER is not open (state: $PR_STATE)"
+              exit 1
+            fi
+
+            echo "checkout-ref=refs/pull/$PR_NUMBER/head" >> "$GITHUB_OUTPUT"
+            echo "Running integration tests for PR #$PR_NUMBER"
+          else
+            if ! echo "$BRANCH" | grep -Eq '^[a-zA-Z0-9_./-]+$'; then
+              echo "::error::Invalid branch name. Only alphanumeric characters, hyphens, underscores, dots, and slashes are allowed."
+              exit 1
+            fi
+
+            echo "checkout-ref=$BRANCH" >> "$GITHUB_OUTPUT"
+            echo "Running integration tests for branch $BRANCH"
+          fi
+
+      - name: Detect changed paths
+        id: detect-changes
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.inputs.pr-number }}
+          BRANCH: ${{ github.event.inputs.branch }}
+          REPO: ${{ github.repository }}
+        run: |
+          if [ -n "$PR_NUMBER" ]; then
+            CHANGED_FILES=$(gh pr diff "$PR_NUMBER" --repo "$REPO" --name-only)
+          else
+            # For branches, compare against main using the GitHub API
+            CHANGED_FILES=$(gh api "repos/$REPO/compare/main...$BRANCH" --jq '.files[].filename')
+          fi
+
+          DOTNET_CHANGES=false
+          PYTHON_CHANGES=false
+
+          if echo "$CHANGED_FILES" | grep -q '^dotnet/'; then
+            DOTNET_CHANGES=true
+          fi
+
+          if echo "$CHANGED_FILES" | grep -q '^python/'; then
+            PYTHON_CHANGES=true
+          fi
+
+          echo "dotnet=$DOTNET_CHANGES" >> "$GITHUB_OUTPUT"
+          echo "python=$PYTHON_CHANGES" >> "$GITHUB_OUTPUT"
+          echo "Detected changes — dotnet: $DOTNET_CHANGES, python: $PYTHON_CHANGES"
+
+  dotnet-integration-tests:
+    name: .NET Integration Tests
+    needs: resolve-ref
+    if: needs.resolve-ref.outputs.dotnet-changes == 'true'
+    uses: ./.github/workflows/dotnet-integration-tests.yml
+    with:
+      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
+    secrets: inherit
+
+  python-integration-tests:
+    name: Python Integration Tests
+    needs: resolve-ref
+    if: needs.resolve-ref.outputs.python-changes == 'true'
+    uses: ./.github/workflows/python-integration-tests.yml
+    with:
+      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
+    secrets: inherit
@@ -29,4 +29,7 @@ jobs:
          token: ${{ secrets.GITHUB_TOKEN }}
          timeout: 3600
          interval: 30
-          ignored: CodeQL,CodeQL analysis (csharp)
+          # "Cleanup artifacts", "Agent", "Prepare", and "Upload results" are check runs
+          # created by an org-level GitHub App (MSDO), not by any workflow in this repo.
+          # They are outside our control and their transient failures should not block merges.
+          ignored: CodeQL,CodeQL analysis (csharp),Cleanup artifacts,Agent,Prepare,Upload results
@@ -0,0 +1,319 @@
+#
+# Dedicated Python integration tests workflow, called from the manual integration test orchestrator.
+# Runs all tests (unit + integration) split into parallel jobs by provider.
+#
+# NOTE: This workflow and python-merge-tests.yml share the same set of parallel
+# test jobs. Keep them in sync — when adding, removing, or modifying a job here,
+# apply the same change to python-merge-tests.yml.
+#
+
+name: python-integration-tests
+
+on:
+  workflow_call:
+    inputs:
+      checkout-ref:
+        description: "Git ref to checkout (e.g., refs/pull/123/head)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  id-token: write
+
+env:
+  UV_CACHE_DIR: /tmp/.uv-cache
+  UV_PYTHON: "3.13"
+
+jobs:
+  # Unit tests: all non-integration tests across all packages
+  python-tests-unit:
+    name: Python Integration Tests - Unit
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (unit tests only)
+        run: >
+          uv run poe all-tests
+          -m "not integration"
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+
+  # OpenAI integration tests
+  python-tests-openai:
+    name: Python Integration Tests - OpenAI
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_EMBEDDINGS_MODEL_ID: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (OpenAI integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/core/tests/openai
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+
+  # Azure OpenAI integration tests
+  python-tests-azure-openai:
+    name: Python Integration Tests - Azure OpenAI
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      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_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      - name: Test with pytest (Azure OpenAI integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/core/tests/azure
+          -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)
+  python-tests-misc-integration:
+    name: Python Integration Tests - Misc
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
+      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (Anthropic, Ollama, MCP integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/anthropic/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
+
+  # Azure Functions + Durable Task integration tests
+  python-tests-functions:
+    name: Python Integration Tests - Functions
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      UV_PYTHON: "3.10"
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      FUNCTIONS_WORKER_RUNTIME: "python"
+      DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
+      AzureWebJobsStorage: "UseDevelopmentStorage=true"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      - name: Set up Azure Functions Integration Test Emulators
+        uses: ./.github/actions/azure-functions-integration-setup
+        id: azure-functions-setup
+      - name: Test with pytest (Functions + Durable Task integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/azurefunctions/tests/integration_tests
+          packages/durabletask/tests/integration_tests
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+
+  # Azure AI integration tests
+  python-tests-azure-ai:
+    name: Python Integration Tests - Azure AI
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    env:
+      AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
+      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
+      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Azure CLI Login
+        uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      - name: Test with pytest
+        timeout-minutes: 15
+        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+
+  # Azure Cosmos integration tests
+  python-tests-cosmos:
+    name: Python Integration Tests - Cosmos
+    runs-on: ubuntu-latest
+    environment: integration
+    timeout-minutes: 60
+    services:
+      cosmosdb:
+        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
+        ports:
+          - 8081:8081
+    env:
+      AZURE_COSMOS_ENDPOINT: "http://localhost:8081/"
+      # Static Azure Cosmos DB emulator key (documented): https://learn.microsoft.com/en-us/azure/cosmos-db/emulator
+      AZURE_COSMOS_KEY: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
+      AZURE_COSMOS_DATABASE_NAME: "agent-framework-cosmos-it-db"
+      AZURE_COSMOS_CONTAINER_NAME: "agent-framework-cosmos-it-container"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.checkout-ref }}
+          persist-credentials: false
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Wait for Cosmos DB emulator
+        run: |
+          for i in {1..60}; do
+            if curl --silent --show-error http://localhost:8081/ > /dev/null; then
+              echo "Cosmos DB emulator is ready."
+              exit 0
+            fi
+            sleep 2
+          done
+          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
+
+  python-integration-tests-check:
+    if: always()
+    runs-on: ubuntu-latest
+    needs:
+      [
+        python-tests-unit,
+        python-tests-openai,
+        python-tests-azure-openai,
+        python-tests-misc-integration,
+        python-tests-functions,
+        python-tests-azure-ai,
+        python-tests-cosmos
+      ]
+    steps:
+      - name: Fail workflow if tests failed
+        if: contains(join(needs.*.result, ','), 'failure')
+        uses: actions/github-script@v8
+        with:
+          script: core.setFailed('Integration Tests Failed!')
+
+      - name: Fail workflow if tests cancelled
+        if: contains(join(needs.*.result, ','), 'cancelled')
+        uses: actions/github-script@v8
+        with:
+          script: core.setFailed('Integration Tests Cancelled!')
@@ -1,4 +1,9 @@
 name: Python - Merge - Tests
+#
+# NOTE: This workflow and python-integration-tests.yml share the same set of
+# parallel test jobs. Keep them in sync — when adding, removing, or modifying a
+# job here, apply the same change to python-integration-tests.yml.
+#

 on:
  workflow_dispatch:
@@ -10,13 +15,13 @@ on:
    - cron: "0 0 * * *" # Run at midnight UTC daily

 permissions:
-  contents: write
+  contents: read
  id-token: write

 env:
  # Configure a constant location for the uv cache
  UV_CACHE_DIR: /tmp/.uv-cache
-  RUN_INTEGRATION_TESTS: "true"
+  UV_PYTHON: "3.13"
  RUN_SAMPLES_TESTS: ${{ vars.RUN_SAMPLES_TESTS }}

 jobs:
@@ -26,7 +31,14 @@ jobs:
      contents: read
      pull-requests: read
    outputs:
-      pythonChanges: ${{ steps.filter.outputs.python}}
+      pythonChanges: ${{ steps.filter.outputs.python }}
+      coreChanged: ${{ steps.filter.outputs.core }}
+      openaiChanged: ${{ steps.filter.outputs.openai }}
+      azureChanged: ${{ steps.filter.outputs.azure }}
+      miscChanged: ${{ steps.filter.outputs.misc }}
+      functionsChanged: ${{ steps.filter.outputs.functions }}
+      azureAiChanged: ${{ steps.filter.outputs.azure-ai }}
+      cosmosChanged: ${{ steps.filter.outputs.cosmos }}
    steps:
      - uses: actions/checkout@v6
      - uses: dorny/paths-filter@v3
@@ -35,6 +47,29 @@ jobs:
          filters: |
            python:
              - 'python/**'
+            core:
+              - 'python/packages/core/agent_framework/_*.py'
+              - 'python/packages/core/agent_framework/_workflows/**'
+              - 'python/packages/core/agent_framework/exceptions.py'
+              - 'python/packages/core/agent_framework/observability.py'
+            openai:
+              - 'python/packages/core/agent_framework/openai/**'
+              - 'python/packages/core/tests/openai/**'
+            azure:
+              - 'python/packages/core/agent_framework/azure/**'
+              - 'python/packages/core/tests/azure/**'
+            misc:
+              - 'python/packages/anthropic/**'
+              - 'python/packages/ollama/**'
+              - 'python/packages/core/agent_framework/_mcp.py'
+              - 'python/packages/core/tests/core/test_mcp.py'
+            functions:
+              - 'python/packages/azurefunctions/**'
+              - 'python/packages/durabletask/**'
+            azure-ai:
+              - 'python/packages/azure-ai/**'
+            cosmos:
+              - 'python/packages/azure-cosmos/**'
      # run only if 'python' files were changed
      - name: python tests
        if: steps.filter.outputs.python == 'true'
@@ -43,34 +78,15 @@ jobs:
      - name: not python tests
        if: steps.filter.outputs.python != 'true'
        run: echo "NOT python file"
-  python-tests-core:
-    name: Python Tests - Core
+  # Unit tests: always run all non-integration tests across all packages
+  python-tests-unit:
+    name: Python Tests - Unit
    needs: paths-filter
-    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
-    runs-on: ${{ matrix.os }}
-    environment: ${{ matrix.environment }}
-    strategy:
-      fail-fast: true
-      matrix:
-        python-version: ["3.10"]
-        os: [ubuntu-latest]
-        environment: ["integration"]
-    env:
-      UV_PYTHON: ${{ matrix.python-version }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
-      # For Azure Functions integration tests
-      FUNCTIONS_WORKER_RUNTIME: "python"
-      DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
-      AzureWebJobsStorage: "UseDevelopmentStorage=true"
-
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true'
+    runs-on: ubuntu-latest
+    environment: integration
    defaults:
      run:
        working-directory: python
@@ -80,11 +96,219 @@ jobs:
        id: python-setup
        uses: ./.github/actions/python-setup
        with:
-          python-version: ${{ matrix.python-version }}
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (unit tests only)
+        run: >
+          uv run poe all-tests
+          -m "not integration"
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+        working-directory: ./python
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Unit test results
+
+  # OpenAI integration tests
+  python-tests-openai:
+    name: Python Tests - OpenAI Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.openaiChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_EMBEDDINGS_MODEL_ID: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (OpenAI integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/core/tests/openai
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
+        working-directory: ./python
+      - name: Test OpenAI samples
+        timeout-minutes: 10
+        if: env.RUN_SAMPLES_TESTS == 'true'
+        run: uv run pytest tests/samples/ -m "openai"
+        working-directory: ./python
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: OpenAI integration test results
+
+  # Azure OpenAI integration tests
+  python-tests-azure-openai:
+    name: Python Tests - Azure OpenAI Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.azureChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    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_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - 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: Test with pytest (Azure OpenAI integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/core/tests/azure
+          -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 samples
+        timeout-minutes: 10
+        if: env.RUN_SAMPLES_TESTS == 'true'
+        run: uv run pytest tests/samples/ -m "azure"
+        working-directory: ./python
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Azure OpenAI integration test results
+
+  # Misc integration tests (Anthropic, Ollama, MCP)
+  python-tests-misc-integration:
+    name: Python Tests - Misc Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.miscChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
+      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Test with pytest (Anthropic, Ollama, MCP integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/anthropic/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
+        working-directory: ./python
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Misc integration test results
+
+  # Azure Functions + Durable Task integration tests
+  python-tests-functions:
+    name: Python Tests - Functions Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.functionsChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    env:
+      UV_PYTHON: "3.10"
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      FUNCTIONS_WORKER_RUNTIME: "python"
+      DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
+      AzureWebJobsStorage: "UseDevelopmentStorage=true"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
          os: ${{ runner.os }}
-        env:
-          # Configure a constant location for the uv cache
-          UV_CACHE_DIR: /tmp/.uv-cache
      - name: Azure CLI Login
        if: github.event_name != 'pull_request'
        uses: azure/login@v2
@@ -95,13 +319,15 @@ jobs:
      - name: Set up Azure Functions Integration Test Emulators
        uses: ./.github/actions/azure-functions-integration-setup
        id: azure-functions-setup
-      - name: Test with pytest
-        run: uv run poe all-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Test core samples
-        timeout-minutes: 10
-        if: env.RUN_SAMPLES_TESTS == 'true'
-        run: uv run pytest tests/samples/ -m "openai" -m "azure"
+      - name: Test with pytest (Functions + Durable Task integration)
+        run: >
+          uv run pytest --import-mode=importlib
+          packages/azurefunctions/tests/integration_tests
+          packages/durabletask/tests/integration_tests
+          -m integration
+          -n logical --dist worksteal
+          --timeout=120 --session-timeout=900 --timeout_method thread
+          --retries 2 --retry-delay 5
        working-directory: ./python
      - name: Surface failing tests
        if: always()
@@ -111,22 +337,20 @@ jobs:
          summary: true
          display-options: fEX
          fail-on-empty: false
-          title: Test results
+          title: Functions integration test results

  python-tests-azure-ai:
    name: Python Tests - Azure AI
    needs: paths-filter
-    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
-    runs-on: ${{ matrix.os }}
-    environment: ${{ matrix.environment }}
-    strategy:
-      fail-fast: true
-      matrix:
-        python-version: ["3.10"]
-        os: [ubuntu-latest]
-        environment: ["integration"]
+    if: >
+      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.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
    env:
-      UV_PYTHON: ${{ matrix.python-version }}
      AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
@@ -139,11 +363,8 @@ jobs:
        id: python-setup
        uses: ./.github/actions/python-setup
        with:
-          python-version: ${{ matrix.python-version }}
+          python-version: ${{ env.UV_PYTHON }}
          os: ${{ runner.os }}
-        env:
-          # Configure a constant location for the uv cache
-          UV_CACHE_DIR: /tmp/.uv-cache
      - name: Azure CLI Login
        if: github.event_name != 'pull_request'
        uses: azure/login@v2
@@ -153,7 +374,7 @@ jobs:
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
      - name: Test with pytest
        timeout-minutes: 15
-        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
        working-directory: ./python
      - name: Test Azure AI samples
        timeout-minutes: 10
@@ -172,16 +393,78 @@ jobs:

  # TODO: Add python-tests-lab

+  # Azure Cosmos integration tests
+  python-tests-cosmos:
+    name: Python Tests - Cosmos Integration
+    needs: paths-filter
+    if: >
+      github.event_name != 'pull_request' &&
+      needs.paths-filter.outputs.pythonChanges == 'true' &&
+      (github.event_name != 'merge_group' ||
+       needs.paths-filter.outputs.cosmosChanged == 'true' ||
+       needs.paths-filter.outputs.coreChanged == 'true')
+    runs-on: ubuntu-latest
+    environment: integration
+    services:
+      cosmosdb:
+        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
+        ports:
+          - 8081:8081
+    env:
+      AZURE_COSMOS_ENDPOINT: "http://localhost:8081/"
+      # Static Azure Cosmos DB emulator key (documented): https://learn.microsoft.com/en-us/azure/cosmos-db/emulator
+      AZURE_COSMOS_KEY: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
+      AZURE_COSMOS_DATABASE_NAME: "agent-framework-cosmos-it-db"
+      AZURE_COSMOS_CONTAINER_NAME: "agent-framework-cosmos-it-container"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ env.UV_PYTHON }}
+          os: ${{ runner.os }}
+      - name: Wait for Cosmos DB emulator
+        run: |
+          for i in {1..60}; do
+            if curl --silent --show-error http://localhost:8081/ > /dev/null; then
+              echo "Cosmos DB emulator is ready."
+              exit 0
+            fi
+            sleep 2
+          done
+          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
+        working-directory: ./python
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Cosmos integration test results
+
  python-integration-tests-check:
    if: always()
    runs-on: ubuntu-latest
    needs:
      [
-        python-tests-core,
-        python-tests-azure-ai
+        python-tests-unit,
+        python-tests-openai,
+        python-tests-azure-openai,
+        python-tests-misc-integration,
+        python-tests-functions,
+        python-tests-azure-ai,
+        python-tests-cosmos,
      ]
    steps:
-
      - name: Fail workflow if tests failed
        id: check_tests_failed
        if: contains(join(needs.*.result, ','), 'failure')
@@ -0,0 +1,302 @@
+name: Python - Sample Validation
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * *" # Run at midnight UTC daily
+
+env:
+  # Configure a constant location for the uv cache
+  UV_CACHE_DIR: /tmp/.uv-cache
+  # GitHub Copilot configuration
+  GITHUB_COPILOT_MODEL: claude-opus-4.6
+  COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  validate-01-get-started:
+    name: Validate 01-get-started
+    runs-on: ubuntu-latest
+    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 }}
+    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: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir 01-get-started --save-report --report-name 01-get-started
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-01-get-started
+          path: python/scripts/sample_validation/reports/
+
+  validate-02-agents:
+    name: Validate 02-agents
+    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 }}
+      # OpenAI configuration
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      # Observability
+      ENABLE_INSTRUMENTATION: "true"
+    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: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir 02-agents --save-report --report-name 02-agents
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-02-agents
+          path: python/scripts/sample_validation/reports/
+
+  validate-03-workflows:
+    name: Validate 03-workflows
+    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 }}
+    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: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir 03-workflows --save-report --report-name 03-workflows
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-03-workflows
+          path: python/scripts/sample_validation/reports/
+
+  validate-04-hosting:
+    name: Validate 04-hosting
+    if: false  # Temporarily disabled because of sample complexity
+    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 }}
+      # A2A configuration
+      A2A_AGENT_HOST: http://localhost:5001/
+    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: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir 04-hosting --save-report --report-name 04-hosting
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-04-hosting
+          path: python/scripts/sample_validation/reports/
+
+  validate-05-end-to-end:
+    name: Validate 05-end-to-end
+    if: false  # Temporarily disabled because of sample complexity
+    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 }}
+      # 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 }}
+    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: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir 05-end-to-end --save-report --report-name 05-end-to-end
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-05-end-to-end
+          path: python/scripts/sample_validation/reports/
+
+  validate-autogen-migration:
+    name: Validate autogen-migration
+    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 }}
+      # OpenAI configuration
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+    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: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir autogen-migration --save-report --report-name autogen-migration
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-autogen-migration
+          path: python/scripts/sample_validation/reports/
+
+  validate-semantic-kernel-migration:
+    name: Validate semantic-kernel-migration
+    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 }}
+      # OpenAI configuration
+      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
+      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
+      # Copilot Studio
+      COPILOTSTUDIOAGENT__ENVIRONMENTID: ${{ secrets.COPILOTSTUDIOAGENT__ENVIRONMENTID }}
+      COPILOTSTUDIOAGENT__SCHEMANAME: ${{ secrets.COPILOTSTUDIOAGENT__SCHEMANAME }}
+      COPILOTSTUDIOAGENT__TENANTID: ${{ secrets.COPILOTSTUDIOAGENT__TENANTID }}
+      COPILOTSTUDIOAGENT__AGENTAPPID: ${{ secrets.COPILOTSTUDIOAGENT__AGENTAPPID }}
+    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: Run sample validation
+        run: |
+          cd scripts && uv run python -m sample_validation --subdir semantic-kernel-migration --save-report --report-name semantic-kernel-migration
+
+      - name: Upload validation report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: validation-report-semantic-kernel-migration
+          path: python/scripts/sample_validation/reports/
@@ -53,7 +53,7 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 ### ✨ **Highlights**

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

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

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

 ### .NET

- [Getting Started with Agents](./dotnet/samples/GettingStarted/Agents): basic agent creation and tool usage
- [Agent Provider Samples](./dotnet/samples/GettingStarted/AgentProviders): samples showing different agent providers
- [Workflow Samples](./dotnet/samples/GettingStarted/Workflows): advanced multi-agent patterns and workflow orchestration
+- [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

 ## Contributor Resources

@@ -11,7 +11,7 @@ model:
        topP: 0.95
    connection:
        kind: key
-        apiKey: =Env.OPENAI_APIKEY
+        apiKey: =Env.OPENAI_API_KEY
 outputSchema:
    properties:
        language:
@@ -498,7 +498,7 @@ We need to decide what AIContent types, each agent response type will be mapped
 | Google ADK | **Approach 1** Both [input and output schemas can be specified for LLM Agents](https://google.github.io/adk-docs/agents/llm-agents/#structuring-data-input_schema-output_schema-output_key) at construction time. This option is specific to this agent type and other agent types do not necessarily support |
 | AWS (Strands) | **Approach 2** Supports a special invocation method called [structured_output](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent/#strands.agent.agent.Agent.structured_output) |
 | LangGraph | **Approach 1** Supports [configuring an agent](https://langchain-ai.github.io/langgraph/agents/agents/?h=structured#6-configure-structured-output) at agent construction time, and a [structured response](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) can be retrieved as a special property on the agent response |
-| Agno | **Approach 1** Supports [configuring an agent](https://docs.agno.com/examples/getting-started/structured-output) at agent construction time |
+| Agno | **Approach 1** Supports [configuring an agent](https://docs.agno.com/input-output/structured-output/agent) at agent construction time |
 | A2A | **Informal Approach 2** Doesn't formally support schema negotiation, but [hints can be provided via metadata](https://a2a-protocol.org/latest/specification/#97-structured-data-exchange-requesting-and-providing-json) at invocation time |
 | Protocol Activity | Supports returning [Complex types](https://github.com/microsoft/Agents/blob/main/specs/activity/protocol-activity.md#complex-types) but no support for requesting a type |

@@ -1114,6 +1114,7 @@ Defaults introduced by this change:
 - `RedisContextProvider.DEFAULT_SOURCE_ID = "redis"`
 - `RedisHistoryProvider.DEFAULT_SOURCE_ID = "redis_memory"`
 - `AzureAISearchContextProvider.DEFAULT_SOURCE_ID = "azure_ai_search"`
+- `FoundryMemoryProvider.DEFAULT_SOURCE_ID = "foundry_memory"`


 ## Comparison to .NET Implementation
@@ -0,0 +1,211 @@
+---
+status: accepted
+contact: westey-m
+date: 2026-02-24
+deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub, lokitoth, alliscode, taochenosu, moonbox3
+consulted:
+informed:
+---
+
+# AdditionalProperties for AIAgent and AgentSession
+
+## Context and Problem Statement
+
+The `AIAgent` base class currently exposes `Id`, `Name`, and `Description` as its core metadata properties, and `AgentSession` exposes only a `StateBag` property.
+Neither type has a mechanism for attaching arbitrary metadata, such as protocol-specific descriptors (e.g., A2A agent cards), hosting attributes, session-level tags, or custom user-defined metadata for discovery and routing.
+
+Other types in the framework already carry `AdditionalProperties` — notably `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate` — all using `AdditionalPropertiesDictionary` from `Microsoft.Extensions.AI`.
+Adding a similar property to `AIAgent` and `AgentSession` would give both types a consistent, extensible metadata surface.
+
+Related: [Work Item #2133](https://github.com/microsoft/agent-framework/issues/2133)
+
+## Decision Drivers
+
+- **Consistency**: Other core types (`AgentRunOptions`, `AgentResponse`, `AgentResponseUpdate`) already expose `AdditionalProperties`. `AIAgent` and `AgentSession` are the major abstractions that lack this.
+- **Extensibility**: Hosting libraries, protocol adapters (A2A, AG-UI), and discovery mechanisms need a place to attach agent-level and session-level metadata without subclassing.
+- **Simplicity**: The solution should be easy to understand and use; avoid over-engineering.
+- **Minimal breaking change**: The addition should not require changes to existing agent implementations.
+- **Clear semantics**: Users should understand what `AdditionalProperties` on an agent or session means and how it differs from `AdditionalProperties` on `AgentRunOptions`.
+
+## Considered Options
+
+### Surface Area
+
+- **Option A**: Public get-only property, auto-initialized (`AdditionalPropertiesDictionary AdditionalProperties { get; } = new()`) on both `AIAgent` and `AgentSession`
+- **Option B**: Public get/set nullable property (`AdditionalPropertiesDictionary? AdditionalProperties { get; set; }`) on both `AIAgent` and `AgentSession`
+- **Option C**: Constructor-injected dictionary with public get-only accessor on both `AIAgent` and `AgentSession`
+- **Option D**: External container/wrapper object — metadata lives outside `AIAgent` and `AgentSession`; no changes to the base classes
+
+### Semantics
+
+- **Option 1**: Metadata only — describes the agent or session; not propagated when calling `IChatClient`
+- **Option 2**: Passed down the stack — merged into `ChatOptions.AdditionalProperties` during `ChatClientAgent` runs
+
+## Decision Outcome
+
+The chosen option is **Option D + Option 1**: an external container/wrapper object, used purely as metadata.
+
+### Consequences
+
+- Good, because `AIAgent` and `AgentSession` remain unchanged, avoiding any increase to the core framework surface area while still enabling extensible metadata.
+- Good, because an external wrapper (owned by hosting/protocol libraries or user code, not the `AIAgent` / `AgentSession` base classes) can internally use `AdditionalPropertiesDictionary` to stay consistent with existing patterns on `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate`.
+- Good, because metadata-only semantics keep a clean separation from per-run extensibility (`AgentRunOptions.AdditionalProperties`) and avoid unexpected side effects during agent execution.
+- Good, because no additional allocation occurs on `AIAgent` or `AgentSession` when no metadata is needed; external wrappers can be created only when metadata is required.
+- Bad, because callers and libraries must manage and pass around both the agent/session instance and its associated metadata wrapper, keeping them correctly associated.
+- Bad, because different hosting or protocol layers may define their own wrapper types, which can fragment the ecosystem unless conventions are agreed upon.
+
+## Pros and Cons of the Options
+
+### Option A — Public get-only property, auto-initialized
+
+The property is always non-null and ready to use. Users add metadata after construction.
+
+```csharp
+public abstract partial class AIAgent
+{
+    public AdditionalPropertiesDictionary AdditionalProperties { get; } = new();
+}
+
+public abstract partial class AgentSession
+{
+    public AdditionalPropertiesDictionary AdditionalProperties { get; } = new();
+}
+
+// Usage
+agent.AdditionalProperties["protocol"] = "A2A";
+agent.AdditionalProperties.Add<MyAgentCardInfo>(cardInfo);
+session.AdditionalProperties["tenant"] = tenantId;
+```
+
+- Good, because users never encounter `null` — no defensive null checks needed.
+- Good, because the dictionary reference cannot be replaced, preventing accidental data loss.
+- Good, because it is the simplest API surface to use.
+- Neutral, because it always allocates, even when no metadata is needed. The allocation cost is negligible.
+- Bad, because it cannot be set at construction time as a single object (users must populate it post-construction).
+
+### Option B — Public get/set nullable property
+
+Matches the existing pattern on `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate`.
+
+```csharp
+public abstract partial class AIAgent
+{
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+}
+
+public abstract partial class AgentSession
+{
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+}
+
+// Usage
+agent.AdditionalProperties ??= new();
+agent.AdditionalProperties["protocol"] = "A2A";
+session.AdditionalProperties ??= new();
+session.AdditionalProperties["tenant"] = tenantId;
+```
+
+- Good, because it is consistent with the existing `AdditionalProperties` pattern on `AgentRunOptions` and `AgentResponse`.
+- Good, because it avoids allocation when no metadata is needed.
+- Bad, because every consumer must null-check before reading or writing.
+- Bad, because the entire dictionary can be replaced, risking accidental loss of metadata set by other components (e.g., a hosting library sets metadata, then user code replaces the dictionary).
+
+### Option C — Constructor-injected with public get
+
+The dictionary is provided at construction time and exposed as get-only.
+
+```csharp
+public abstract partial class AIAgent
+{
+    public AdditionalPropertiesDictionary AdditionalProperties { get; }
+
+    protected AIAgent(AdditionalPropertiesDictionary? additionalProperties = null)
+    {
+        this.AdditionalProperties = additionalProperties ?? new();
+    }
+}
+
+public abstract partial class AgentSession
+{
+    public AdditionalPropertiesDictionary AdditionalProperties { get; }
+
+    protected AgentSession(AdditionalPropertiesDictionary? additionalProperties = null)
+    {
+        this.AdditionalProperties = additionalProperties ?? new();
+    }
+}
+```
+
+- Good, because an agent's metadata can be established before any code runs against it.
+- Bad, because `AdditionalPropertiesDictionary` has no read-only variant, so the constructor-injection pattern gives a false sense of immutability — callers can still mutate the dictionary contents after construction.
+- Bad, because it requires adding a constructor parameter to the abstract base classes, which is a source-breaking change for all existing `AIAgent` and `AgentSession` subclasses (even with a default value, it changes the constructor signature that derived classes chain to).
+- Bad, because it is more complex with little practical benefit over Option A, since post-construction mutation is equally possible.
+
+### Option D — External container/wrapper object
+
+Rather than adding `AdditionalProperties` to `AIAgent` or `AgentSession`, users wrap the agent or session in a container object that carries both the instance and any associated metadata. No changes to the base classes are required.
+
+```csharp
+public class AgentWithMetadata
+{
+    public required AIAgent Agent { get; init; }
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+}
+
+public class SessionWithMetadata
+{
+    public required AgentSession Session { get; init; }
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+}
+
+// Usage
+var wrapper = new AgentWithMetadata
+{
+    Agent = myAgent,
+    AdditionalProperties = new() { ["protocol"] = "A2A" }
+};
+```
+
+- Good, because it requires no changes to `AIAgent` or `AgentSession`, avoiding any risk of breaking existing implementations.
+- Good, because metadata is clearly external to the agent and session, eliminating any ambiguity about whether it might be passed down the execution stack.
+- Good, because the container pattern gives the user full control over the metadata lifecycle and serialization.
+- Bad, because it is not discoverable — users must know about the container convention; there is no built-in API surface guiding them.
+
+### Option 1 — Metadata only
+
+`AdditionalProperties` on `AIAgent` and `AgentSession` is descriptive metadata. It is **not** automatically propagated when the agent calls downstream services such as `IChatClient`.
+
+- Good, because it keeps a clean separation of concerns: agent/session-level metadata vs. per-run options.
+- Good, because it avoids unintended side effects — metadata added for discovery or hosting won't leak into LLM requests.
+- Good, because per-run extensibility is already served by `AgentRunOptions.AdditionalProperties` (see [ADR 0014](0014-feature-collections.md)), so there is no gap.
+- Neutral, because users who want to pass agent metadata to the chat client can still do so manually via `AgentRunOptions`.
+
+### Option 2 — Passed down the stack
+
+`AdditionalProperties` on `AIAgent` and `AgentSession` are automatically merged into `ChatOptions.AdditionalProperties` (or similar) when `ChatClientAgent` invokes the underlying `IChatClient`.
+
+- Good, because it provides an automatic way to send agent-level configuration to the LLM provider.
+- Bad, because it conflates metadata (describing the agent) with operational parameters (controlling LLM behavior), leading to potential confusion.
+- Bad, because it risks leaking unrelated metadata into LLM calls (e.g., hosting tags, discovery URLs).
+- Bad, because it would be `ChatClientAgent`-specific behavior on a base-class property, creating inconsistency for non-`ChatClientAgent` implementations.
+- Bad, because it duplicates the purpose of `AgentRunOptions.AdditionalProperties`, which already serves as the per-run extensibility point for passing data down the stack.
+
+## Serialization Considerations
+
+`AIAgent` instances are not typically serialized, so `AdditionalProperties` on `AIAgent` does not raise serialization concerns.
+
+`AgentSession` instances, however, are routinely serialized and deserialized — for example, to persist conversation state across application restarts. Adding `AdditionalProperties` to `AgentSession` introduces a serialization challenge: `AdditionalPropertiesDictionary` is a `Dictionary<string, object?>`, and `object?` values do not carry enough type information for the JSON deserializer to reconstruct the original CLR types.
+
+### Default behavior — JsonElement round-tripping
+
+By default, when an `AgentSession` with `AdditionalProperties` is serialized and later deserialized, any complex objects stored as values in the dictionary will be deserialized as `JsonElement` rather than their original types. This is the same behavior exhibited by `ChatMessage.AdditionalProperties` and other `AdditionalPropertiesDictionary` usages in `Microsoft.Extensions.AI`, and is the approach we will follow.
+
+### Custom serialization via JsonSerializerOptions
+
+`AIAgent.SerializeSessionAsync` and `AIAgent.DeserializeSessionAsync` already accept an optional `JsonSerializerOptions` parameter. Users who need strongly-typed round-tripping of `AdditionalProperties` values can supply custom options with appropriate converters or type info resolvers. This is non-trivial to implement but provides full control over deserialization behavior when needed.
+
+## More Information
+
+- [ADR 0014 — Feature Collections](0014-feature-collections.md) established that `AdditionalProperties` on `AgentRunOptions` serves as the per-run extensibility mechanism. The proposed agent-level and session-level properties serve a complementary, distinct purpose: static metadata describing the agent or session itself.
+- `AdditionalPropertiesDictionary` is defined in `Microsoft.Extensions.AI` and is already a dependency of `Microsoft.Agents.AI.Abstractions`. No new package references are needed.
+- Type-safe access is available via the existing `AdditionalPropertiesExtensions` helper methods (`Add<T>`, `TryGetValue<T>`, `Contains<T>`, `Remove<T>`), which use `typeof(T).FullName` as the dictionary key.
@@ -0,0 +1,163 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+contact: westey-m
+date: 2026-02-25
+deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub
+consulted: 
+informed:
+---
+
+# AgentSession serialization
+
+## Context and Problem Statement
+
+Serializing AgentSessions is done today by calling SerializeSession on the AIAgent instance and deserialization
+is done via the DeserializeSession method on the AIAgent instance.
+
+This approach has some drawbacks:
+
+1. It requires each AgentSession implementation to implement its own serialization logic. This can lead to inconsistencies and errors if not done correctly.
+1. It means that only one serialization format can be supported at a time. If we want to support multiple formats (e.g., JSON, XML, binary), we would need to implement separate serialization logic for each format.
+1. It is not possible to serialize and deserialize lists of AgentSessions, since each need to be handled individually.
+1. Users may not realise that they need to call these specific methods to serialize/deserialize AgentSessions.
+
+The reason why this approach was chosen initially is that AgentSessions may have behaviors that are attached to them and only the agent knows what behaviors to attach.
+These behaviors also have their own state that are attached to the AgentSession.
+The behaviors may have references to SDKs or other resources that cannot be created via standard deserialization mechanisms.
+E.g. an AgentSession may have a custom ChatMessageStore that knows how to store chat history in a specific storage backend and has a reference to the SDK client for that backend.
+When deserializing the AgentSession, we need to make sure that the ChatMessageStore is created with the correct SDK client.
+
+## Decision Drivers
+
+- A. Ability to continue to support custom behaviors (AIContextProviders / ChatHistoryProviders).
+- B. Ability to serialize and deserialize AgentSessions via standard serialization mechanisms, e.g. JsonSerializer.Serialize and JsonSerializer.Deserialize.
+- C. Ability for the caller to access custom providers.
+
+## Considered Options
+
+- Option 1: Separate state from behavior, serialize state only and re-attach behavior on first usage
+- Option 2: Separate state from behavior, and only have state on AgentSession
+- Option 3: Keep the current approach of custom Serialize/Deserialize methods
+
+### Option 1: Separate state from behavior, serialize state only and re-attach behavior on first usage
+
+Decision Drivers satisfied: A, B and C (C only partially)
+
+Have separate properties on the AgentSession for state and behavior and mark the behavior property with [JsonIgnore].
+After deserializing the AgentSession, the behavior is null and when the AgentSession is first used by the Agent, the behavior is created and attached to the AgentSession.
+
+This requires polymorphic deserialization to be supported, so that the correct AgentSession subclass and the correct behavior state is created during deserialization.
+Since the implementations for AgentSessions and their behaviors are not all known at compile time, we need a way to register custom AgentSession types and their corresponding behavior types for serialization with System.Text.Json on our JsonUtilities helpers.
+
+A drawback of this approach is that the AgentSession is in an incomplete state after deserialization until it is first used,
+so if a user was to call `GetService<MyBehavior>()` on the AgentSession before it is used by the Agent, it would return null.
+
+Behaviors like ChatMessageStore and AIContextProviders would need to change to support taking state as input and exposing state publicly.
+
+```csharp
+public class ChatClientAgentSession
+{
+    ...
+    public ChatMessageStoreState ChatMessageStoreState { get; }
+    public ChatMessageStore? ChatMessageStore { get; }
+    ...
+}
+
+[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
+[JsonDerivedType(typeof(InMemoryChatMessageStoreState), nameof(InMemoryChatMessageStoreState))]
+public abstract class ChatMessageStoreState
+{
+}
+public class InMemoryChatMessageStoreState : ChatMessageStoreState
+{
+    public IList<ChatMessage> Messages { get; set; } = [];
+}
+
+public abstract class ChatMessageStore<TState>
+    where TState : ChatMessageStoreState
+{
+    ...
+    public abstract TState State { get; }
+    ...
+}
+
+public sealed class InMemoryChatMessageStore : ChatMessageStore<InMemoryChatMessageStoreState>, IList<ChatMessage>
+{
+    private readonly InMemoryChatMessageStoreState _state;
+
+    public InMemoryChatMessageStore(InMemoryChatMessageStoreState? state)
+    {
+        this._state = state ?? new InMemoryChatMessageStoreState();
+    }
+
+    public override InMemoryChatMessageStoreState State => this._state;
+
+    ...
+}
+```
+
+ChatClientAgent factories would need to change to support creating behaviors based on state:
+
+```csharp
+    public Func<ChatMessageStoreFactoryContext, ChatMessageStore>? ChatMessageStoreFactory { get; set; }
+
+    public class ChatMessageStoreFactoryContext
+    {
+        public ChatMessageStoreState? State { get; set; }
+    }
+```
+
+The run behavior of the ChatClientAgent would be as follows:
+
+1. If an AgentSession is provided, check if the ChatMessageStore property is null.
+1. If it is, check if the ChatMessageStoreState property is null.
+    1. If ChatMessageStoreState is null, check if there is a provided ChatMessageStoreFactory.
+        1. If there is, call it with a ChatMessageStoreFactoryContext containing null State to create a default ChatMessageStore behavior, and update the AgentSession with the created behavior and its state.
+        2. If there is not, create a default InMemoryChatMessageStore behavior, and update the AgentSession with the created behavior and its state.
+    1. If ChatMessageStoreState is not null, check if there is a provided ChatMessageStoreFactory.
+        1. If there is, call it with a ChatMessageStoreFactoryContext containing the State to create a ChatMessageStore behavior based on the state.
+        2. If there is not, create an InMemoryChatMessageStore behavior based on the State.
+
+### Option 2: Separate state from behavior, and only have state on AgentSession
+
+Decision Drivers satisfied: A, B and C.
+
+This is similar to Option 1 but instead of having a behavior property on the AgentSession, we only have a StateBag property on the AgentSession.
+Behaviors really make more sense to live with the agent rather than the Session, but state should live on the session.
+When the AgentSession is used by the Agent, the Agent runs the behaviors against the Session, and the behavior stores it's state on the Session StateBag.
+
+This means that users are unable to access the behavior from the AgentSession, e.g. via `AgentSession.GetService<TBehavior>()`.
+
+However, the behaviors can be public properties on the Agent or can be retrieved from the agent via `AIAgent.GetService<MyAIContextProvider>()`.
+
+```csharp
+public class AgentSession
+{
+    ...
+    public AgentSessionStateBag StateBag { get; protected set; } = new();
+    ...
+}
+```
+
+### Option 3: Keep the current approach of custom Serialize/Deserialize methods
+
+Decision Drivers satisfied: A and C
+
+This option keeps the current approach of having custom Serialize/Deserialize methods on the AgentSession and AIAgent.
+
+## Decision Outcome
+
+Chosen option:
+
+**Option 2** — separate state from behavior, with only state on the AgentSession — because it satisfies all decision drivers and provides the cleanest separation of concerns. Since not all AgentSession implementations have yet been cleanly separated from their behaviors, AIAgent.SerializeSession and AIAgent.DeserializeSession is kept for the time being, but most session types can be serialized and deserialized directly using JsonSerializer.
+
+### Consequences
+
+- Good, because providers are fully stateless — the same provider instance works correctly across any number of concurrent sessions without risk of state leakage.
+- Good, because `AgentSession` can be serialized and deserialized with standard `System.Text.Json` mechanisms, satisfying decision driver B.
+- Good, because the generic `StateBag` is extensible — new providers can store arbitrary state without requiring changes to the session class.
+- Good, because users can access providers via the agent (e.g. `agent.GetService<InMemoryChatHistoryProvider>()`) satisfying decision driver C.
+- Good, because sessions are always in a complete and valid state after deserialization — there is no "incomplete until first use" problem as in Option 1.
+- Neutral, because providers cannot be accessed directly from the session; callers must go through the agent. This is a minor usability trade-off but keeps the session focused on state only.
+- Bad, because each provider must be disciplined about using `ProviderSessionState<T>` and not storing session-specific data in instance fields. This is a correctness concern for custom provider implementers.
@@ -8,7 +8,7 @@ This directory contains feature documentation for the durable agents integration

 - .NET implementation: `dotnet/src/Microsoft.Agents.AI.DurableTask/` and `dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/`
 - Python implementation: `python/packages/durabletask/` and `python/packages/azurefunctions/` (package `agent-framework-azurefunctions`)
- .NET samples: `dotnet/samples/Durable/Agents/`
+- .NET samples: `dotnet/samples/04-hosting/DurableAgents/`
 - Python samples: `python/samples/04-hosting/durabletask/`
 - Official docs (Microsoft Learn): <https://learn.microsoft.com/agent-framework/integrations/azure-functions>

@@ -219,7 +219,7 @@ When using the [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-

 ## Samples

- **.NET** – [Console app samples](../../../dotnet/samples/Durable/Agents/ConsoleApps/) and [Azure Functions samples](../../../dotnet/samples/Durable/Agents/AzureFunctions/) covering single-agent, chaining, concurrency, conditionals, human-in-the-loop, long-running tools, MCP tool exposure, and reliable streaming.
+- **.NET** – [Console app samples](../../../dotnet/samples/04-hosting/DurableAgents/ConsoleApps/) and [Azure Functions samples](../../../dotnet/samples/04-hosting/DurableAgents/AzureFunctions/) covering single-agent, chaining, concurrency, conditionals, human-in-the-loop, long-running tools, MCP tool exposure, and reliable streaming.
 - **Python** – [Durable Task samples](../../../python/samples/04-hosting/durabletask/) covering single-agent, multi-agent, streaming, chaining, concurrency, conditionals, and human-in-the-loop.

 ## Packages
@@ -0,0 +1,390 @@
+# Vector Stores and Embeddings
+
+## Overview
+
+This feature ports the vector store abstractions, embedding generator abstractions, and their implementations from Semantic Kernel into Agent Framework. The ported code follows AF's coding standards, feels native to AF, and is structured to allow data models/schemas to be reusable across both frameworks. The embedding abstraction combines the best of SK's `EmbeddingGeneratorBase` and MEAI's `IEmbeddingGenerator<TInput, TEmbedding>`.
+
+| Capability | Description |
+| --- | --- |
+| Embedding generation | Generic embedding client abstraction supporting text, image, and audio inputs |
+| Vector store collections | CRUD operations on vector store collections (upsert, get, delete) |
+| Vector search | Unified search interface with `search_type` parameter (`"vector"`, `"keyword_hybrid"`) |
+| Data model decorator | `@vectorstoremodel` decorator for defining vector store data models (supports Pydantic, dataclasses, plain classes, dicts) |
+| Agent tools | `create_search_tool`, `create_upsert_tool`, `create_get_tool`, `create_delete_tool` for agent-usable vector store operations |
+| In-memory store | Zero-dependency vector store for testing and development |
+| 13+ connectors | Azure AI Search, Qdrant, Redis, PostgreSQL, MongoDB, Cosmos DB, Pinecone, Chroma, Weaviate, Oracle, SQL Server, FAISS |
+
+## Key Design Decisions
+
+### Embedding Abstractions (combining SK + MEAI)
+- **Both Protocol and Base class** (matching AF's `SupportsChatGetResponse` + `BaseChatClient` pattern):
+  - `SupportsGetEmbeddings` — Protocol for duck-typing
+  - `BaseEmbeddingClient` — ABC base class for implementations (similar to `BaseChatClient`)
+- **Generic input type** (`EmbeddingInputT`, default `str`) from MEAI — allows image/audio embeddings in the future
+- **Generic output type** (`EmbeddingT`, default `list[float]`) from MEAI — supports `list[float]`, `list[int]`, `bytes`, etc.
+- **Generic order**: `[EmbeddingInputT, EmbeddingT, EmbeddingOptionsT]` — options last, matching MEAI's `IEmbeddingGenerator<TInput, TEmbedding>` with options appended
+- **TypeVar naming convention**: Use `SuffixT` per AF standard (e.g., `EmbeddingInputT`, `EmbeddingT`, `ModelT`, `KeyT`)
+- `EmbeddingGenerationOptions` TypedDict (inspired by MEAI, matching AF's `ChatOptions` pattern) — `total=False`, includes `dimensions`, `model_id`. No `additional_properties` since each implementation extends with its own fields.
+- Protocol and base class are generic over input, output, and options: `SupportsGetEmbeddings[EmbeddingInputT, EmbeddingT, OptionsContraT]`, `BaseEmbeddingClient[EmbeddingInputT, EmbeddingT, OptionsCoT]`
+- **`Embedding[EmbeddingT]` type** in `_types.py` — a lightweight generic class (not Pydantic) with `vector: EmbeddingT`, `model_id: str | None`, `dimensions: int | None` (explicit or computed from vector), `created_at: datetime | None`, `additional_properties: dict[str, Any]`
+- **`GeneratedEmbeddings[EmbeddingT, EmbeddingOptionsT]` type** — a list-like container of `Embedding[EmbeddingT]` objects with `options: EmbeddingOptionsT | None` (stores the options used to generate), `usage: dict[str, Any] | None`, `additional_properties: dict[str, Any]`
+- **No numpy dependency** — return `list[float]` by default; users cast as needed
+
+### Vector Store Abstractions
+- **Port core abstractions without Pydantic for internal classes** — use plain classes
+- **Both Protocol and Base class** for vector store operations (matching AF pattern):
+  - `SupportsVectorUpsert` / `SupportsVectorSearch` — Protocols for duck-typing (follows `Supports<Capability>` naming convention)
+  - `BaseVectorCollection` / `BaseVectorSearch` — ABC base classes for implementations
+  - `BaseVectorStore` — ABC base class for store operations (factory for collections, no protocol needed)
+- **TypeVar naming convention**: `ModelT`, `KeyT`, `FilterT` (suffix T, per AF standard)
+- **Support Pydantic for user-facing data models** — the `@vectorstoremodel` decorator and `VectorStoreCollectionDefinition` should work with Pydantic models, dataclasses, plain classes, and dicts
+- **Remove SK-specific dependencies** — no `KernelBaseModel`, `KernelFunction`, `KernelParameterMetadata`, `kernel_function`, `PromptExecutionSettings`
+- **Embedding types in `_types.py`**, embedding protocol/base class in `_clients.py`
+- **All vector store specific types, enums, protocols, base classes** in `_vectors.py`
+- **Error handling** uses AF's exception hierarchy (e.g., `IntegrationException` variants)
+
+### Package Structure
+- **Embedding types** (`Embedding`, `GeneratedEmbeddings`, `EmbeddingGenerationOptions`) in `agent_framework/_types.py`
+- **Embedding protocol + base class** (`SupportsGetEmbeddings`, `BaseEmbeddingClient`) in `agent_framework/_clients.py`
+- **All vector store specific code** in a new `agent_framework/_vectors.py` module — this includes:
+  - Enums: `FieldTypes`, `IndexKind`, `DistanceFunction`
+  - `VectorStoreField`, `VectorStoreCollectionDefinition`
+  - `SearchOptions`, `SearchResponse`, `RecordFilterOptions`
+  - `@vectorstoremodel` decorator
+  - Serialization/deserialization protocols
+  - `VectorStoreRecordHandler`, `BaseVectorCollection`, `BaseVectorStore`, `BaseVectorSearch`
+  - `SupportsVectorUpsert`, `SupportsVectorSearch` protocols
+- **OpenAI embeddings** in `agent_framework/openai/` (built into core, like OpenAI chat)
+- **Azure OpenAI embeddings** in `agent_framework/azure/` (built into core, follows `AzureOpenAIChatClient` pattern)
+- **Each vector store connector** in its own AF package under `packages/`
+- **In-memory store** in core (no external deps)
+- **TextSearch and its implementations** (Brave, Google) — last phase, separate work
+
+## Naming: SK → AF
+
+### Names that change
+
+| SK Name | AF Name | Rationale |
+|---------|---------|-----------|
+| `VectorStoreCollection` | `BaseVectorCollection` | Drop redundant `Store`, add `Base` prefix per AF pattern |
+| `VectorStore` | `BaseVectorStore` | Add `Base` prefix per AF pattern |
+| `VectorSearch` | `BaseVectorSearch` | Add `Base` prefix per AF pattern |
+| `VectorSearchOptions` | `SearchOptions` | Shorter — context is already vector search |
+| `VectorSearchResult` | `SearchResponse` | Align with `ChatResponse`/`AgentResponse` |
+| `GetFilteredRecordOptions` | `RecordFilterOptions` | Shorter, more natural |
+| `EmbeddingGeneratorBase` | `BaseEmbeddingClient` | Matches AF `BaseChatClient` pattern |
+| `VectorStoreCollectionProtocol` | `SupportsVectorUpsert` | AF `Supports*` naming convention |
+| `VectorSearchProtocol` | `SupportsVectorSearch` | AF `Supports*` naming convention |
+| `__kernel_vectorstoremodel__` | `__vectorstoremodel__` | Drop SK `kernel` prefix |
+| `__kernel_vectorstoremodel_definition__` | `__vectorstoremodel_definition__` | Drop SK `kernel` prefix |
+| `search()` + `hybrid_search()` | `search(search_type=...)` | Single method with `Literal` parameter |
+| `SearchType` enum | `Literal["vector", "keyword_hybrid"]` | No enum, just a literal |
+| `KernelSearchResults` | `SearchResults` | Drop SK `Kernel` prefix (plural — container of `SearchResponse` items) |
+
+### Names that stay the same
+
+| Name | Location |
+|------|----------|
+| `@vectorstoremodel` | `_vectors.py` |
+| `VectorStoreField` | `_vectors.py` |
+| `VectorStoreCollectionDefinition` | `_vectors.py` |
+| `VectorStoreRecordHandler` | `_vectors.py` |
+| `FieldTypes` | `_vectors.py` |
+| `IndexKind` | `_vectors.py` |
+| `DistanceFunction` | `_vectors.py` |
+| `DISTANCE_FUNCTION_DIRECTION_HELPER` | `_vectors.py` |
+| `Embedding` | `_types.py` |
+| `GeneratedEmbeddings` | `_types.py` |
+| `EmbeddingGenerationOptions` | `_types.py` |
+| `SupportsGetEmbeddings` | `_clients.py` |
+
+### New AF-only names (no SK equivalent)
+
+| Name | Location | Purpose |
+|------|----------|---------|
+| `BaseEmbeddingClient` | `_clients.py` | ABC base for embedding implementations |
+| `EmbeddingInputT` | `_types.py` | TypeVar for generic embedding input (default `str`) |
+| `EmbeddingTelemetryLayer` | `observability.py` | MRO-based OTel tracing for embeddings |
+| `SupportsVectorUpsert` | `_vectors.py` | Protocol for collection CRUD |
+| `SupportsVectorSearch` | `_vectors.py` | Protocol for vector search |
+| `create_search_tool` | `_vectors.py` | Creates AF `FunctionTool` from vector search |
+
+## Source Files Reference (SK → AF mapping)
+
+### SK Source Files
+| SK File | Lines | Content |
+|---------|-------|---------|
+| `data/vector.py` | 2369 | All vector store abstractions, enums, decorator, search |
+| `data/_shared.py` | 184 | SearchOptions, KernelSearchResults, shared search types |
+| `data/text_search.py` | 349 | TextSearch base, TextSearchResult |
+| `connectors/ai/embedding_generator_base.py` | 50 | EmbeddingGeneratorBase ABC |
+| `connectors/in_memory.py` | 520 | InMemoryCollection, InMemoryStore |
+| `connectors/azure_ai_search.py` | 793 | Azure AI Search collection + store |
+| `connectors/azure_cosmos_db.py` | 1104 | Cosmos DB (Mongo + NoSQL) |
+| `connectors/redis.py` | 845 | Redis (Hashset + JSON) |
+| `connectors/qdrant.py` | 653 | Qdrant collection + store |
+| `connectors/postgres.py` | 987 | PostgreSQL collection + store |
+| `connectors/mongodb.py` | 633 | MongoDB Atlas collection + store |
+| `connectors/pinecone.py` | 691 | Pinecone collection + store |
+| `connectors/chroma.py` | 484 | Chroma collection + store |
+| `connectors/faiss.py` | 278 | FAISS (extends InMemory) |
+| `connectors/weaviate.py` | 804 | Weaviate collection + store |
+| `connectors/oracle.py` | 1267 | Oracle collection + store |
+| `connectors/sql_server.py` | 1132 | SQL Server collection + store |
+| `connectors/ai/open_ai/services/open_ai_text_embedding.py` | 91 | OpenAI embedding impl |
+| `connectors/ai/open_ai/services/open_ai_text_embedding_base.py` | 78 | OpenAI embedding base |
+| `connectors/brave.py` | ~200 | Brave TextSearch impl |
+| `connectors/google_search.py` | ~200 | Google TextSearch impl |
+
+---
+
+## Implementation Phases
+
+### Phase 1: Core Embedding Abstractions & OpenAI Implementation ✅ DONE
+**Goal:** Establish the embedding generator abstraction and ship one working implementation.
+**Mergeable:** Yes — adds new types/protocols, no breaking changes.
+**Status:** Merged via PR #4153. Closes sub-issue #4163.
+
+#### 1.1 — Embedding types in `_types.py`
+- `EmbeddingInputT` TypeVar (default `str`) — generic input type for embedding generation
+- `EmbeddingT` TypeVar (default `list[float]`) — generic output embedding vector type
+- `Embedding[EmbeddingT]` generic class: `vector: EmbeddingT`, `model_id: str | None`, `dimensions: int | None` (explicit param or computed from vector length), `created_at: datetime | None`, `additional_properties: dict[str, Any]`
+- `GeneratedEmbeddings[EmbeddingT, EmbeddingOptionsT]` generic class: list-like container of `Embedding[EmbeddingT]` objects with `options: EmbeddingOptionsT | None` (the options used to generate), `usage: dict[str, Any] | None`, `additional_properties: dict[str, Any]`
+- `EmbeddingGenerationOptions` TypedDict (`total=False`): `dimensions: int`, `model_id: str` — follows the same pattern as `ChatOptions`. No `additional_properties` needed since it's a TypedDict and each implementation can extend with its own fields.
+
+#### 1.2 — Embedding generator protocol + base class in `_clients.py`
+- `SupportsGetEmbeddings(Protocol[EmbeddingInputT, EmbeddingT, OptionsContraT])`: generic over input, output, and options (all with defaults), `get_embeddings(values: Sequence[EmbeddingInputT], *, options: OptionsContraT | None = None) -> Awaitable[GeneratedEmbeddings[EmbeddingT]]`
+- `BaseEmbeddingClient(ABC, Generic[EmbeddingInputT, EmbeddingT, OptionsCoT])`: ABC base class mirroring `BaseChatClient` pattern
+  - `__init__` with `additional_properties`, etc.
+  - Abstract `get_embeddings(...)` for subclasses to implement directly (no `_inner_*` indirection — simpler than chat, no middleware needed)
+- `EmbeddingTelemetryLayer` in `observability.py` — MRO-based telemetry (no closure), `gen_ai.operation.name = "embeddings"`
+
+#### 1.3 — OpenAI embedding generator in `agent_framework/openai/` and `agent_framework/azure/`
+- `RawOpenAIEmbeddingClient` — implements `get_embeddings` via `_ensure_client()` factory
+- `OpenAIEmbeddingClient(OpenAIConfigMixin, EmbeddingTelemetryLayer[str, list[float], OptionsT], RawOpenAIEmbeddingClient[OptionsT])` — full client with config + telemetry layers
+- `OpenAIEmbeddingOptions(EmbeddingGenerationOptions)` — extends with `encoding_format`, `user`
+- `AzureOpenAIEmbeddingClient` in `agent_framework/azure/` — follows `AzureOpenAIChatClient` pattern with `AzureOpenAIConfigMixin`, `load_settings`, Entra ID credential support
+- `AzureOpenAISettings` extended with `embedding_deployment_name` (env var: `AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME`)
+
+#### 1.4 — Tests and samples
+- Unit tests for types, protocol, base class, OpenAI client, Azure OpenAI client
+- Integration tests for OpenAI and Azure OpenAI (gated behind credentials check, `@pytest.mark.flaky`)
+- Samples in `samples/02-agents/embeddings/` — `openai_embeddings.py`, `azure_openai_embeddings.py`
+
+---
+
+### Phase 2: Embedding Generators for Existing Providers
+**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.2 — Ollama embedding (in `packages/ollama/`)
+#### 2.3 — Anthropic embedding (in `packages/anthropic/`)
+#### 2.4 — Bedrock embedding (in `packages/bedrock/`)
+
+---
+
+### Phase 3: Core Vector Store Abstractions
+**Goal:** Establish all vector store types, enums, the decorator, collection definition, and base classes.
+**Mergeable:** Yes — adds new abstractions, no breaking changes.
+
+#### 3.1 — Vector store enums and field types in `_vectors.py`
+- `FieldTypes` enum: `KEY`, `VECTOR`, `DATA`
+- `IndexKind` enum: `HNSW`, `FLAT`, `IVF_FLAT`, `DISK_ANN`, `QUANTIZED_FLAT`, `DYNAMIC`, `DEFAULT`
+- `DistanceFunction` enum: `COSINE_SIMILARITY`, `COSINE_DISTANCE`, `DOT_PROD`, `EUCLIDEAN_DISTANCE`, `EUCLIDEAN_SQUARED_DISTANCE`, `MANHATTAN`, `HAMMING`, `DEFAULT`
+- No `SearchType` enum — use `Literal["vector", "keyword_hybrid"]` instead, per AF convention of avoiding unnecessary imports
+- `VectorStoreField` plain class (not Pydantic)
+- `VectorStoreCollectionDefinition` class (not Pydantic internally, but supports Pydantic models as input)
+- `SearchOptions` plain class — includes `score_threshold: float | None` for filtering results by score (see note below)
+- `SearchResponse` generic class
+- `RecordFilterOptions` plain class
+- `DISTANCE_FUNCTION_DIRECTION_HELPER` dict
+
+#### 3.2 — `@vectorstoremodel` decorator
+- Port from SK, works with dataclasses, Pydantic models, plain classes, and dicts
+- Sets `__vectorstoremodel__` and `__vectorstoremodel_definition__` on the class
+- Remove SK-specific `kernel` prefix (`__kernel_vectorstoremodel__` → `__vectorstoremodel__`)
+
+#### 3.3 — Serialization/deserialization protocols
+- `SerializeMethodProtocol`, `ToDictFunctionProtocol`, `FromDictFunctionProtocol`, etc.
+- Port the record handler logic but without Pydantic base class — use plain class or ABC
+
+#### 3.4 — Vector store base classes in `_vectors.py`
+- `VectorStoreRecordHandler` — internal base class that handles serialization/deserialization between user data models and store-specific formats, plus embedding generation for vector fields. Both `BaseVectorCollection` and `BaseVectorSearch` extend this.
+- `BaseVectorCollection(VectorStoreRecordHandler)` — base for collections
+  - Uses `SupportsGetEmbeddings` instead of `EmbeddingGeneratorBase`
+  - Not a Pydantic model — use `__init__` with explicit params
+  - `upsert`, `get`, `delete`, `ensure_collection_exists`, `collection_exists`, `ensure_collection_deleted`
+  - Async context manager support
+- `BaseVectorStore` — base for stores
+  - `get_collection`, `list_collection_names`, `collection_exists`, `ensure_collection_deleted`
+  - Async context manager support
+
+#### 3.5 — Vector search base class
+- `BaseVectorSearch(VectorStoreRecordHandler)` — base for vector search
+  - Single `search(search_type=...)` method with `search_type: Literal["vector", "keyword_hybrid"]` parameter — no enum, just a literal
+  - `_inner_search` abstract method for implementations
+  - Filter building with lambda parser (AST-based)
+  - Vector generation from values using embedding generator
+
+#### 3.6 — Protocols for type checking
+- `SupportsVectorUpsert` — Protocol for upsert/get/delete operations
+- `SupportsVectorSearch` — Protocol for vector search (single `search()` with `search_type` parameter)
+- No separate `SupportsVectorHybridSearch` — search type is a parameter, not a separate capability
+- No protocol for `VectorStore` — it's a factory for collections, not a capability to duck-type against
+
+#### 3.7 — Exception types
+- Add vector store exceptions under `IntegrationException` or create new branch
+- `VectorStoreException`, `VectorStoreOperationException`, `VectorSearchException`, `VectorStoreModelException`, etc.
+
+#### 3.8 — `create_search_tool` on `BaseVectorSearch`
+- Method on `BaseVectorSearch` that creates an AF `FunctionTool` from the vector search
+- Wraps the single `search()` method, passing `search_type` parameter
+- Accepts: `name`, `description`, `search_type`, `top`, `skip`, `filter`, `string_mapper`
+- The tool takes a query string, vectorizes it, searches, and returns results as strings
+- Can also be a standalone factory function in `_vectors.py`
+
+#### 3.9 — Tests for all vector store abstractions
+- Unit tests for enums, field types, collection definition
+- Unit tests for decorator
+- Unit tests for serialization/deserialization
+- Unit tests for record handler
+
+---
+
+### Phase 4: In-Memory Vector Store
+**Goal:** Provide a zero-dependency vector store for testing and development.
+**Mergeable:** Yes — first usable vector store.
+
+#### 4.1 — Port `InMemoryCollection` and `InMemoryStore` into core
+- Place in `agent_framework/_vectors.py` (alongside the abstractions)
+- Supports vector search (cosine similarity, etc.)
+- No external dependencies
+
+#### 4.2 — Port FAISS extension (optional, can be separate package)
+- Extends InMemory with FAISS indexing
+
+#### 4.3 — Tests and sample code
+
+---
+
+### Phase 5: Vector Store Connectors — Tier 1 (High Priority)
+**Goal:** Ship the most commonly used vector store connectors.
+**Mergeable:** Yes — each connector is independent.
+
+Each connector follows the AF package structure:
+- New package under `packages/`
+- Own `pyproject.toml`, `tests/`, lazy loading in core
+
+#### 5.1 — Azure AI Search (`packages/azure-ai-search/`)
+- May extend existing package or be new
+- `AzureAISearchCollection`, `AzureAISearchStore`
+
+#### 5.2 — Qdrant (`packages/qdrant/`)
+- New package
+- `QdrantCollection`, `QdrantStore`
+
+#### 5.3 — Redis (`packages/redis/`)
+- May extend existing redis package
+- `RedisCollection` (JSON + Hashset variants), `RedisStore`
+
+#### 5.4 — PostgreSQL/pgvector (`packages/postgres/`)
+- New package
+- `PostgresCollection`, `PostgresStore`
+
+---
+
+### Phase 6: Vector Store Connectors — Tier 2
+**Goal:** Ship remaining vector store connectors.
+**Mergeable:** Yes — each connector is independent.
+
+#### 6.1 — MongoDB Atlas (`packages/mongodb/`)
+#### 6.2 — Azure Cosmos DB (`packages/azure-cosmos-db/`)
+- Cosmos Mongo + Cosmos NoSQL
+#### 6.3 — Pinecone (`packages/pinecone/`)
+#### 6.4 — Chroma (`packages/chroma/`)
+#### 6.5 — Weaviate (`packages/weaviate/`)
+
+---
+
+### Phase 7: Vector Store Connectors — Tier 3
+**Goal:** Ship niche or less common connectors.
+**Mergeable:** Yes — each connector is independent.
+
+#### 7.1 — Oracle (`packages/oracle/`)
+#### 7.2 — SQL Server (`packages/sql-server/`)
+#### 7.3 — FAISS (`packages/faiss/` or in core extending InMemory)
+
+> **Note:** When implementing any SQL-based connector (PostgreSQL, SQL Server, SQLite, Cosmos DB), review the .NET MEVD changes made by @roji (Shay Rojansky) in SK for design patterns, query building, filter translation, and feature parity: https://github.com/microsoft/semantic-kernel/pulls?q=is%3Apr+author%3Aroji+is%3Aclosed
+
+---
+
+### Phase 8: Vector Store CRUD Tools
+**Goal:** Provide a full set of agent-usable tools for CRUD operations on vector store collections.
+**Mergeable:** Yes — adds tools without changing existing APIs.
+
+#### 8.1 — `create_upsert_tool` — tool for upserting records into a collection
+#### 8.2 — `create_get_tool` — tool for retrieving records by key
+- Key-based lookup only (by primary key), not a search tool
+- Documentation must clearly distinguish this from `create_search_tool`: get_tool retrieves specific records by their known key, while search_tool performs similarity/filtered search across the collection
+- Consider if this overlaps with filtered search and document when to use which
+#### 8.3 — `create_delete_tool` — tool for deleting records by key
+#### 8.4 — Tests and samples for CRUD tools
+
+---
+
+### Phase 9: Additional Embedding Implementations (New Providers)
+**Goal:** Provide embedding generators for providers that don't yet have AF packages.
+**Mergeable:** Yes — each is independent, new packages.
+
+#### 9.1 — HuggingFace/ONNX embedding (new package or lab)
+#### 9.2 — Mistral AI embedding (new package)
+#### 9.3 — Google AI / Vertex AI embedding (new package)
+#### 9.4 — Nvidia embedding (new package)
+
+---
+
+### Phase 10: TextSearch Abstractions & Implementations (Separate Work)
+**Goal:** Port text search (non-vector) abstractions and implementations.
+**Mergeable:** Yes — independent of vector stores.
+
+#### 10.1 — TextSearch base class and types
+- `SearchOptions`, `SearchResponse`, `TextSearchResult`
+- `TextSearch` base class with `search()` method
+- `create_search_function()` for kernel integration (may need AF equivalent)
+
+#### 10.2 — Brave Search implementation
+#### 10.3 — Google Search implementation
+#### 10.4 — Vector store text search bridge (connecting VectorSearch to TextSearch interface)
+
+---
+
+## Key Considerations
+
+1. **No Pydantic for internal classes**: All AF internal classes should use plain classes. Pydantic is only used for user-facing input validation (e.g., vector store data models).
+
+2. **Protocol + Base class**: Follow AF's pattern of both a `Protocol` for duck-typing and a `Base` ABC for implementation, matching how `SupportsChatGetResponse` + `BaseChatClient` works.
+
+3. **Exception hierarchy**: Use AF's `IntegrationException` branch for vector store operations, since vector stores are external dependencies.
+
+4. **`from __future__ import annotations`**: Required in all files per AF coding standard.
+
+5. **No `**kwargs` escape hatches in public APIs**: For user-facing interfaces, use explicit named parameters per AF coding standard. Internal implementation details (e.g., cooperative multiple inheritance / MRO patterns) may use `**kwargs` where necessary, as long as they are not exposed in public signatures.
+
+6. **Lazy loading**: Connector packages use `__getattr__` lazy loading in core provider folders.
+
+7. **Reusable data models**: The `@vectorstoremodel` decorator and `VectorStoreCollectionDefinition` should be agnostic enough to work with both SK and AF. The core types (`FieldTypes`, `IndexKind`, `DistanceFunction`, `VectorStoreField`) should be identical or easily mapped.
+
+8. **`create_search_tool`**: The AF-native equivalent of SK's `create_search_function`. Instead of creating a `KernelFunction`, this creates an AF `FunctionTool` (via the `@tool` decorator pattern) from a vector search. This allows agents to use vector search as a tool during conversations. Design:
+   - `create_search_tool(name, description, search_type, ...)` → returns a `FunctionTool` that wraps `VectorSearch.search(search_type=...)`
+   - The tool accepts a query string, performs embedding + vector search, and returns results as strings
+   - Supports configurable string mappers, filter functions, top/skip defaults
+   - Lives in `_vectors.py` as a method on `BaseVectorSearch` and/or as a standalone factory function
+
+9. **CRUD tools**: A full set of create/read/update/delete tools for vector store collections, allowing agents to manage data in vector stores. Design:
+   - `create_upsert_tool(...)` → tool for upserting records
+   - `create_get_tool(...)` → tool for retrieving records by key
+   - `create_delete_tool(...)` → tool for deleting records
+   - These are separate from search and are placed in a later phase
+
+10. **Score threshold filtering**: `SearchOptions` includes `score_threshold: float | None` to filter search results by relevance score (ref: [SK .NET PR #13501](https://github.com/microsoft/semantic-kernel/pull/13501)). The semantics depend on the distance function: for similarity functions (cosine similarity, dot product), results *below* the threshold are filtered out; for distance functions (cosine distance, euclidean), results *above* the threshold are filtered out. Use `DISTANCE_FUNCTION_DIRECTION_HELPER` to determine direction. Connectors should implement this natively where the database supports it, falling back to client-side post-filtering otherwise.
@@ -29,6 +29,7 @@ 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.
 - **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`
@@ -19,8 +19,8 @@
    <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
    <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
    <!-- Azure.* -->
-    <PackageVersion Include="Azure.AI.Projects" Version="1.2.0-beta.5" />
-    <PackageVersion Include="Azure.AI.Projects.OpenAI" Version="1.0.0-beta.5" />
+    <PackageVersion Include="Azure.AI.Projects" Version="2.0.0-beta.1" />
+    <PackageVersion Include="Azure.AI.Projects.OpenAI" Version="2.0.0-beta.1" />
    <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.8" />
    <PackageVersion Include="Azure.AI.OpenAI" Version="2.8.0-beta.1" />
    <PackageVersion Include="Azure.Identity" Version="1.17.1" />
@@ -35,7 +35,7 @@
    <!-- System.* -->
    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.3" />
    <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
-    <PackageVersion Include="System.ClientModel" Version="1.8.1" />
+    <PackageVersion Include="System.ClientModel" Version="1.9.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" />
@@ -58,6 +58,8 @@
    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.13.0" />
    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.13.0" />
    <!-- Microsoft.AspNetCore.* -->
+    <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="10.0.0" />
    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
    <!-- Microsoft.Extensions.* -->
@@ -92,7 +94,7 @@
    <PackageVersion Include="Microsoft.SemanticKernel.Agents.AzureAI" Version="1.67.0-preview" />
    <PackageVersion Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.67.0" />
    <!-- Agent SDKs -->
-    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.23" />
+    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.29" />
    <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
    <!-- M365 Agents SDK -->
    <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
@@ -111,9 +113,9 @@
    <!-- Identity -->
    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.78.0" />
    <!-- Workflows -->
-    <PackageVersion Include="Microsoft.Agents.ObjectModel" Version="2026.2.3.1" />
-    <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.2.3.1" />
-    <PackageVersion Include="Microsoft.Agents.ObjectModel.PowerFx" Version="2026.2.3.1" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel" Version="2026.2.4.1" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.2.4.1" />
+    <PackageVersion Include="Microsoft.Agents.ObjectModel.PowerFx" Version="2026.2.4.1" />
    <PackageVersion Include="Microsoft.PowerFx.Interpreter" Version="1.8.1" />
    <!-- Durable Task -->
    <PackageVersion Include="Microsoft.DurableTask.Client" Version="1.18.0" />
@@ -185,4 +187,4 @@
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>
-</Project>
+</Project>
@@ -1,11 +1,5 @@
 # Get Started with Microsoft Agent Framework for C# Developers

-## Samples
-
- [Getting Started with Agents](./samples/GettingStarted/Agents): basic agent creation and tool usage
- [Agent Provider Samples](./samples/GettingStarted/AgentProviders): samples showing different agent providers
- [Workflow Samples](./samples/GettingStarted/Workflows): advanced multi-agent patterns and workflow orchestration
-
 ## Quickstart

 ### Basic Agent - .NET
@@ -28,9 +22,9 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram

 ## Examples & Samples

- [Getting Started with Agents](./samples/GettingStarted/Agents): basic agent creation and tool usage
- [Agent Provider Samples](./samples/GettingStarted/AgentProviders): samples showing different agent providers
- [Workflow Samples](./samples/GettingStarted/Workflows): advanced multi-agent patterns and workflow orchestration
+- [Getting Started with Agents](./samples/02-agents/Agents): basic agent creation and tool usage
+- [Agent Provider Samples](./samples/02-agents/AgentProviders): samples showing different agent providers
+- [Workflow Samples](./samples/03-workflows): advanced multi-agent patterns and workflow orchestration

 ## Agent Framework Documentation

@@ -5,221 +5,189 @@
    <BuildType Name="Release" />
  </Configurations>
  <Folder Name="/Samples/">
+    <File Path="samples/AGENTS.md" />
    <File Path="samples/README.md" />
  </Folder>
-  <Folder Name="/Samples/A2AClientServer/">
-    <File Path="samples/A2AClientServer/README.md" />
-    <Project Path="samples/A2AClientServer/A2AClient/A2AClient.csproj" />
-    <Project Path="samples/A2AClientServer/A2AServer/A2AServer.csproj" />
+  <Folder Name="/Samples/01-get-started/">
+    <Project Path="samples/01-get-started/01_hello_agent/01_hello_agent.csproj" />
+    <Project Path="samples/01-get-started/02_add_tools/02_add_tools.csproj" />
+    <Project Path="samples/01-get-started/03_multi_turn/03_multi_turn.csproj" />
+    <Project Path="samples/01-get-started/04_memory/04_memory.csproj" />
+    <Project Path="samples/01-get-started/05_first_workflow/05_first_workflow.csproj" />
+    <Project Path="samples/01-get-started/06_host_your_agent/06_host_your_agent.csproj" />
  </Folder>
-  <Folder Name="/Samples/AgentWebChat/">
-    <Project Path="samples/AgentWebChat/AgentWebChat.AgentHost/AgentWebChat.AgentHost.csproj" />
-    <Project Path="samples/AgentWebChat/AgentWebChat.AppHost/AgentWebChat.AppHost.csproj" />
-    <Project Path="samples/AgentWebChat/AgentWebChat.ServiceDefaults/AgentWebChat.ServiceDefaults.csproj" />
-    <Project Path="samples/AgentWebChat/AgentWebChat.Web/AgentWebChat.Web.csproj" />
+  <Folder Name="/Samples/02-agents/">
+    <File Path="samples/02-agents/README.md" />
  </Folder>
-  <Folder Name="/Samples/AGUIClientServer/">
-    <Project Path="samples/AGUIClientServer/AGUIClient/AGUIClient.csproj" />
-    <Project Path="samples/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj" />
-    <Project Path="samples/AGUIClientServer/AGUIServer/AGUIServer.csproj" />
+  <Folder Name="/Samples/02-agents/AgentProviders/">
+    <File Path="samples/02-agents/AgentProviders/README.md" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_A2A/Agent_With_A2A.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_Anthropic/Agent_With_Anthropic.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureAIAgentsPersistent/Agent_With_AzureAIAgentsPersistent.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureAIProject/Agent_With_AzureAIProject.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureFoundryModel/Agent_With_AzureFoundryModel.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Agent_With_AzureOpenAIChatCompletion.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureOpenAIResponses/Agent_With_AzureOpenAIResponses.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_CustomImplementation/Agent_With_CustomImplementation.csproj" />
+    <Project Path="samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj" />
+    <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/Durable/" />
-  <Folder Name="/Samples/Durable/Agents/" />
-  <Folder Name="/Samples/Durable/Agents/AzureFunctions/">
-    <File Path="samples/Durable/Agents/AzureFunctions/.editorconfig" />
-    <File Path="samples/Durable/Agents/AzureFunctions/README.md" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/01_SingleAgent/01_SingleAgent.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/06_LongRunningTools/06_LongRunningTools.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/07_AgentAsMcpTool/07_AgentAsMcpTool.csproj" />
-    <Project Path="samples/Durable/Agents/AzureFunctions/08_ReliableStreaming/08_ReliableStreaming.csproj" />
+  <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" />
+    <Project Path="samples/02-agents/Agents/Agent_Step02_StructuredOutput/Agent_Step02_StructuredOutput.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step03_PersistedConversations/Agent_Step03_PersistedConversations.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step04_3rdPartyChatHistoryStorage/Agent_Step04_3rdPartyChatHistoryStorage.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step05_Observability/Agent_Step05_Observability.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step06_DependencyInjection/Agent_Step06_DependencyInjection.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step07_AsMcpTool/Agent_Step07_AsMcpTool.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step08_UsingImages/Agent_Step08_UsingImages.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step09_AsFunctionTool/Agent_Step09_AsFunctionTool.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step10_BackgroundResponsesWithToolsAndPersistence/Agent_Step10_BackgroundResponsesWithToolsAndPersistence.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step11_Middleware/Agent_Step11_Middleware.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step12_Plugins/Agent_Step12_Plugins.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step13_ChatReduction/Agent_Step13_ChatReduction.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step14_BackgroundResponses/Agent_Step14_BackgroundResponses.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step15_DeepResearch/Agent_Step15_DeepResearch.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step16_Declarative/Agent_Step16_Declarative.csproj" />
+    <Project Path="samples/02-agents/Agents/Agent_Step17_AdditionalAIContext/Agent_Step17_AdditionalAIContext.csproj" />
  </Folder>
-  <Folder Name="/Samples/Durable/Agents/ConsoleApps/">
-    <File Path="samples/Durable/Agents/ConsoleApps/README.md" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/01_SingleAgent/01_SingleAgent.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/06_LongRunningTools/06_LongRunningTools.csproj" />
-    <Project Path="samples/Durable/Agents/ConsoleApps/07_ReliableStreaming/07_ReliableStreaming.csproj" />
+  <Folder Name="/Samples/02-agents/DeclarativeAgents/">
+    <Project Path="samples/02-agents/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/">
-    <File Path="samples/GettingStarted/README.md" />
+  <Folder Name="/Samples/02-agents/AGUI/">
+    <File Path="samples/02-agents/AGUI/README.md" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/A2A/">
-    <File Path="samples/GettingStarted/A2A/README.md" />
-    <Project Path="samples/GettingStarted/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
-    <Project Path="samples/GettingStarted/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
+  <Folder Name="/Samples/02-agents/AGUI/Step01_GettingStarted/">
+    <Project Path="samples/02-agents/AGUI/Step01_GettingStarted/Client/Client.csproj" />
+    <Project Path="samples/02-agents/AGUI/Step01_GettingStarted/Server/Server.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/AgentProviders/">
-    <File Path="samples/GettingStarted/AgentProviders/README.md" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_A2A/Agent_With_A2A.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_Anthropic/Agent_With_Anthropic.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureAIAgentsPersistent/Agent_With_AzureAIAgentsPersistent.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureAIProject/Agent_With_AzureAIProject.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureFoundryModel/Agent_With_AzureFoundryModel.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Agent_With_AzureOpenAIChatCompletion.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIResponses/Agent_With_AzureOpenAIResponses.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_CustomImplementation/Agent_With_CustomImplementation.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_Ollama/Agent_With_Ollama.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_ONNX/Agent_With_ONNX.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIAssistants/Agent_With_OpenAIAssistants.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIChatCompletion/Agent_With_OpenAIChatCompletion.csproj" />
-    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIResponses/Agent_With_OpenAIResponses.csproj" />
+  <Folder Name="/Samples/02-agents/AGUI/Step02_BackendTools/">
+    <Project Path="samples/02-agents/AGUI/Step02_BackendTools/Client/Client.csproj" />
+    <Project Path="samples/02-agents/AGUI/Step02_BackendTools/Server/Server.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/Agents/">
-    <File Path="samples/GettingStarted/Agents/README.md" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step01_Running/Agent_Step01_Running.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step02_MultiturnConversation/Agent_Step02_MultiturnConversation.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step03_UsingFunctionTools/Agent_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step04_UsingFunctionToolsWithApprovals/Agent_Step04_UsingFunctionToolsWithApprovals.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Agent_Step05_StructuredOutput.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step06_PersistedConversations/Agent_Step06_PersistedConversations.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step07_3rdPartyChatHistoryStorage/Agent_Step07_3rdPartyChatHistoryStorage.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step08_Observability/Agent_Step08_Observability.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step09_DependencyInjection/Agent_Step09_DependencyInjection.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step10_AsMcpTool/Agent_Step10_AsMcpTool.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step11_UsingImages/Agent_Step11_UsingImages.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step12_AsFunctionTool/Agent_Step12_AsFunctionTool.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step13_BackgroundResponsesWithToolsAndPersistence/Agent_Step13_BackgroundResponsesWithToolsAndPersistence.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step14_Middleware/Agent_Step14_Middleware.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step15_Plugins/Agent_Step15_Plugins.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step16_ChatReduction/Agent_Step16_ChatReduction.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/Agent_Step17_BackgroundResponses.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step18_DeepResearch/Agent_Step18_DeepResearch.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step19_Declarative/Agent_Step19_Declarative.csproj" />
-    <Project Path="samples/GettingStarted/Agents/Agent_Step20_AdditionalAIContext/Agent_Step20_AdditionalAIContext.csproj" />
+  <Folder Name="/Samples/02-agents/AGUI/Step03_FrontendTools/">
+    <Project Path="samples/02-agents/AGUI/Step03_FrontendTools/Client/Client.csproj" />
+    <Project Path="samples/02-agents/AGUI/Step03_FrontendTools/Server/Server.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/DeclarativeAgents/">
-    <Project Path="samples/GettingStarted/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
+  <Folder Name="/Samples/02-agents/AGUI/Step04_HumanInLoop/">
+    <Project Path="samples/02-agents/AGUI/Step04_HumanInLoop/Client/Client.csproj" />
+    <Project Path="samples/02-agents/AGUI/Step04_HumanInLoop/Server/Server.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/">
-    <File Path="samples/GettingStarted/AGUI/README.md" />
+  <Folder Name="/Samples/02-agents/AgentSkills/">
+    <File Path="samples/02-agents/AgentSkills/README.md" />
+    <Project Path="samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Agent_Step01_BasicSkills.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/Step01_GettingStarted/">
-    <Project Path="samples/GettingStarted/AGUI/Step01_GettingStarted/Client/Client.csproj" />
-    <Project Path="samples/GettingStarted/AGUI/Step01_GettingStarted/Server/Server.csproj" />
+  <Folder Name="/Samples/02-agents/AGUI/Step05_StateManagement/">
+    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Client/Client.csproj" />
+    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Server/Server.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/Step02_BackendTools/">
-    <Project Path="samples/GettingStarted/AGUI/Step02_BackendTools/Client/Client.csproj" />
-    <Project Path="samples/GettingStarted/AGUI/Step02_BackendTools/Server/Server.csproj" />
+  <Folder Name="/Samples/02-agents/DevUI/">
+    <File Path="samples/02-agents/DevUI/README.md" />
+    <Project Path="samples/02-agents/DevUI/DevUI_Step01_BasicUsage/DevUI_Step01_BasicUsage.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/Step03_FrontendTools/">
-    <Project Path="samples/GettingStarted/AGUI/Step03_FrontendTools/Client/Client.csproj" />
-    <Project Path="samples/GettingStarted/AGUI/Step03_FrontendTools/Server/Server.csproj" />
+  <Folder Name="/Samples/02-agents/AgentWithAnthropic/">
+    <File Path="samples/02-agents/AgentWithAnthropic/README.md" />
+    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step01_Running/Agent_Anthropic_Step01_Running.csproj" />
+    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning/Agent_Anthropic_Step02_Reasoning.csproj" />
+    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/Agent_Anthropic_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/Step04_HumanInLoop/">
-    <Project Path="samples/GettingStarted/AGUI/Step04_HumanInLoop/Client/Client.csproj" />
-    <Project Path="samples/GettingStarted/AGUI/Step04_HumanInLoop/Server/Server.csproj" />
+  <Folder Name="/Samples/02-agents/AgentWithMemory/">
+    <File Path="samples/02-agents/AgentWithMemory/README.md" />
+    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/AgentWithMemory_Step01_ChatHistoryMemory.csproj" />
+    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/AgentWithMemory_Step02_MemoryUsingMem0.csproj" />
+    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/AgentWithMemory_Step04_MemoryUsingFoundry.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/AGUI/Step05_StateManagement/">
-    <Project Path="samples/GettingStarted/AGUI/Step05_StateManagement/Client/Client.csproj" />
-    <Project Path="samples/GettingStarted/AGUI/Step05_StateManagement/Server/Server.csproj" />
+  <Folder Name="/Samples/02-agents/AgentWithOpenAI/">
+    <File Path="samples/02-agents/AgentWithOpenAI/README.md" />
+    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step01_Running/Agent_OpenAI_Step01_Running.csproj" />
+    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Agent_OpenAI_Step02_Reasoning.csproj" />
+    <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" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/DevUI/">
-    <File Path="samples/GettingStarted/DevUI/README.md" />
-    <Project Path="samples/GettingStarted/DevUI/DevUI_Step01_BasicUsage/DevUI_Step01_BasicUsage.csproj" />
+  <Folder Name="/Samples/02-agents/AgentWithRAG/">
+    <File Path="samples/02-agents/AgentWithRAG/README.md" />
+    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/AgentWithRAG_Step01_BasicTextRAG.csproj" />
+    <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" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/AgentWithAnthropic/">
-    <File Path="samples/GettingStarted/AgentWithAnthropic/README.md" />
-    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step01_Running/Agent_Anthropic_Step01_Running.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning/Agent_Anthropic_Step02_Reasoning.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/Agent_Anthropic_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj" />
+  <Folder Name="/Samples/02-agents/FoundryAgents/">
+    <File Path="samples/02-agents/FoundryAgents/README.md" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming/FoundryAgents_Evaluations_Step01_RedTeaming.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/FoundryAgents_Evaluations_Step02_SelfReflection.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step01.1_Basics/FoundryAgents_Step01.1_Basics.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step01.2_Running/FoundryAgents_Step01.2_Running.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/FoundryAgents_Step02_MultiturnConversation.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step03_UsingFunctionTools/FoundryAgents_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step04_UsingFunctionToolsWithApprovals/FoundryAgents_Step04_UsingFunctionToolsWithApprovals.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step05_StructuredOutput/FoundryAgents_Step05_StructuredOutput.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step06_PersistedConversations/FoundryAgents_Step06_PersistedConversations.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step07_Observability/FoundryAgents_Step07_Observability.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step08_DependencyInjection/FoundryAgents_Step08_DependencyInjection.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step09_UsingMcpClientAsTools/FoundryAgents_Step09_UsingMcpClientAsTools.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step10_UsingImages/FoundryAgents_Step10_UsingImages.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step11_AsFunctionTool/FoundryAgents_Step11_AsFunctionTool.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step12_Middleware/FoundryAgents_Step12_Middleware.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step13_Plugins/FoundryAgents_Step13_Plugins.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step14_CodeInterpreter/FoundryAgents_Step14_CodeInterpreter.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step15_ComputerUse/FoundryAgents_Step15_ComputerUse.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step16_FileSearch/FoundryAgents_Step16_FileSearch.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step17_OpenAPITools/FoundryAgents_Step17_OpenAPITools.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step18_BingCustomSearch/FoundryAgents_Step18_BingCustomSearch.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step19_SharePoint/FoundryAgents_Step19_SharePoint.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step20_MicrosoftFabric/FoundryAgents_Step20_MicrosoftFabric.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step21_WebSearch/FoundryAgents_Step21_WebSearch.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step22_MemorySearch/FoundryAgents_Step22_MemorySearch.csproj" />
+    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step23_LocalMCP/FoundryAgents_Step23_LocalMCP.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/AgentWithMemory/">
-    <File Path="samples/GettingStarted/AgentWithMemory/README.md" />
-    <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/AgentWithMemory_Step01_ChatHistoryMemory.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/AgentWithMemory_Step02_MemoryUsingMem0.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step03_CustomMemory/AgentWithMemory_Step03_CustomMemory.csproj" />
+  <Folder Name="/Samples/02-agents/ModelContextProtocol/">
+    <File Path="samples/02-agents/ModelContextProtocol/README.md" />
+    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
+    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
+    <Project Path="samples/02-agents/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
+    <Project Path="samples/02-agents/ModelContextProtocol/ResponseAgent_Hosted_MCP/ResponseAgent_Hosted_MCP.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/AgentWithOpenAI/">
-    <File Path="samples/GettingStarted/AgentWithOpenAI/README.md" />
-    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step01_Running/Agent_OpenAI_Step01_Running.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Agent_OpenAI_Step02_Reasoning.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj" />
+  <Folder Name="/Samples/02-agents/Observability/">
+    <Project Path="samples/02-agents/AgentOpenTelemetry/AgentOpenTelemetry.csproj" />
  </Folder>
-  <Folder Name="/Samples/Purview/" />
-  <Folder Name="/Samples/Purview/AgentWithPurview/">
-    <Project Path="samples/Purview/AgentWithPurview/AgentWithPurview.csproj" />
+  <Folder Name="/Samples/03-workflows/">
+    <File Path="samples/03-workflows/README.md" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/AgentWithRAG/">
-    <File Path="samples/GettingStarted/AgentWithRAG/README.md" />
-    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/AgentWithRAG_Step01_BasicTextRAG.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/AgentWithRAG_Step02_CustomVectorStoreRAG.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/AgentWithRAG_Step03_CustomRAGDataSource.csproj" />
-    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step04_FoundryServiceRAG/AgentWithRAG_Step04_FoundryServiceRAG.csproj" />
+  <Folder Name="/Samples/03-workflows/Concurrent/">
+    <Project Path="samples/03-workflows/Concurrent/Concurrent/Concurrent.csproj" />
+    <Project Path="samples/03-workflows/Concurrent/MapReduce/MapReduce.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/FoundryAgents/">
-    <File Path="samples/GettingStarted/FoundryAgents/README.md" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.1_Basics/FoundryAgents_Step01.1_Basics.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.2_Running/FoundryAgents_Step01.2_Running.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/FoundryAgents_Step02_MultiturnConversation.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step03_UsingFunctionTools/FoundryAgents_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step04_UsingFunctionToolsWithApprovals/FoundryAgents_Step04_UsingFunctionToolsWithApprovals.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step05_StructuredOutput/FoundryAgents_Step05_StructuredOutput.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step06_PersistedConversations/FoundryAgents_Step06_PersistedConversations.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step07_Observability/FoundryAgents_Step07_Observability.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step08_DependencyInjection/FoundryAgents_Step08_DependencyInjection.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step09_UsingMcpClientAsTools/FoundryAgents_Step09_UsingMcpClientAsTools.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step10_UsingImages/FoundryAgents_Step10_UsingImages.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step11_AsFunctionTool/FoundryAgents_Step11_AsFunctionTool.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step12_Middleware/FoundryAgents_Step12_Middleware.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step13_Plugins/FoundryAgents_Step13_Plugins.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step14_CodeInterpreter/FoundryAgents_Step14_CodeInterpreter.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step15_ComputerUse/FoundryAgents_Step15_ComputerUse.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step19_OpenAPITools/FoundryAgents_Step19_OpenAPITools.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step18_FileSearch/FoundryAgents_Step18_FileSearch.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming/FoundryAgents_Evaluations_Step01_RedTeaming.csproj" />
-    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/FoundryAgents_Evaluations_Step02_SelfReflection.csproj" />
+  <Folder Name="/Samples/03-workflows/ConditionalEdges/">
+    <Project Path="samples/03-workflows/ConditionalEdges/01_EdgeCondition/01_EdgeCondition.csproj" />
+    <Project Path="samples/03-workflows/ConditionalEdges/02_SwitchCase/02_SwitchCase.csproj" />
+    <Project Path="samples/03-workflows/ConditionalEdges/03_MultiSelection/03_MultiSelection.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/ModelContextProtocol/">
-    <File Path="samples/GettingStarted/ModelContextProtocol/README.md" />
-    <Project Path="samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
-    <Project Path="samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
-    <Project Path="samples/GettingStarted/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
-    <Project Path="samples/GettingStarted/ModelContextProtocol/ResponseAgent_Hosted_MCP/ResponseAgent_Hosted_MCP.csproj" />
+  <Folder Name="/Samples/03-workflows/Declarative/">
+    <File Path="samples/03-workflows/Declarative/README.md" />
+    <Project Path="samples/03-workflows/Declarative/ConfirmInput/ConfirmInput.csproj" />
+    <Project Path="samples/03-workflows/Declarative/CustomerSupport/CustomerSupport.csproj" />
+    <Project Path="samples/03-workflows/Declarative/DeepResearch/DeepResearch.csproj" />
+    <Project Path="samples/03-workflows/Declarative/ExecuteCode/ExecuteCode.csproj" />
+    <Project Path="samples/03-workflows/Declarative/ExecuteWorkflow/ExecuteWorkflow.csproj" />
+    <Project Path="samples/03-workflows/Declarative/FunctionTools/FunctionTools.csproj" />
+    <Project Path="samples/03-workflows/Declarative/GenerateCode/GenerateCode.csproj" />
+    <Project Path="samples/03-workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
+    <Project Path="samples/03-workflows/Declarative/InputArguments/InputArguments.csproj" />
+    <Project Path="samples/03-workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj" />
+    <Project Path="samples/03-workflows/Declarative/InvokeMcpTool/InvokeMcpTool.csproj" />
+    <Project Path="samples/03-workflows/Declarative/Marketing/Marketing.csproj" />
+    <Project Path="samples/03-workflows/Declarative/StudentTeacher/StudentTeacher.csproj" />
+    <Project Path="samples/03-workflows/Declarative/ToolApproval/ToolApproval.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/Observability/">
-    <Project Path="samples/GettingStarted/AgentOpenTelemetry/AgentOpenTelemetry.csproj" />
-  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/">
-    <File Path="samples/GettingStarted/Workflows/README.md" />
-  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Concurrent/">
-    <Project Path="samples/GettingStarted/Workflows/Concurrent/Concurrent/Concurrent.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Concurrent/MapReduce/MapReduce.csproj" />
-  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/ConditionalEdges/">
-    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/01_EdgeCondition/01_EdgeCondition.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/02_SwitchCase/02_SwitchCase.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/03_MultiSelection/03_MultiSelection.csproj" />
-  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Declarative/">
-    <File Path="samples/GettingStarted/Workflows/Declarative/README.md" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/ConfirmInput/ConfirmInput.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/CustomerSupport/CustomerSupport.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/DeepResearch/DeepResearch.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/ExecuteCode/ExecuteCode.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/ExecuteWorkflow/ExecuteWorkflow.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/FunctionTools/FunctionTools.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/GenerateCode/GenerateCode.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/InputArguments/InputArguments.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/Marketing/Marketing.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/StudentTeacher/StudentTeacher.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/ToolApproval/ToolApproval.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj" />
-  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Declarative/Examples/">
+  <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" />
@@ -227,60 +195,114 @@
    <File Path="../workflow-samples/README.md" />
    <File Path="../workflow-samples/wttr.json" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/SharedStates/">
-    <Project Path="samples/GettingStarted/Workflows/SharedStates/SharedStates.csproj" />
+  <Folder Name="/Samples/03-workflows/SharedStates/">
+    <Project Path="samples/03-workflows/SharedStates/SharedStates.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Loop/">
-    <Project Path="samples/GettingStarted/Workflows/Loop/Loop.csproj" />
+  <Folder Name="/Samples/03-workflows/Loop/">
+    <Project Path="samples/03-workflows/Loop/Loop.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Agents/">
-    <Project Path="samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Agents/FoundryAgent/FoundryAgent.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Agents/GroupChatToolApproval/GroupChatToolApproval.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/WorkflowAsAnAgent.csproj" />
+  <Folder Name="/Samples/03-workflows/Agents/">
+    <Project Path="samples/03-workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj" />
+    <Project Path="samples/03-workflows/Agents/FoundryAgent/FoundryAgent.csproj" />
+    <Project Path="samples/03-workflows/Agents/GroupChatToolApproval/GroupChatToolApproval.csproj" />
+    <Project Path="samples/03-workflows/Agents/WorkflowAsAnAgent/WorkflowAsAnAgent.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Checkpoint/">
-    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointAndRehydrate/CheckpointAndRehydrate.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointAndResume/CheckpointAndResume.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointWithHumanInTheLoop/CheckpointWithHumanInTheLoop.csproj" />
+  <Folder Name="/Samples/03-workflows/Checkpoint/">
+    <Project Path="samples/03-workflows/Checkpoint/CheckpointAndRehydrate/CheckpointAndRehydrate.csproj" />
+    <Project Path="samples/03-workflows/Checkpoint/CheckpointAndResume/CheckpointAndResume.csproj" />
+    <Project Path="samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop/CheckpointWithHumanInTheLoop.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/HumanInTheLoop/">
-    <Project Path="samples/GettingStarted/Workflows/HumanInTheLoop/HumanInTheLoopBasic/HumanInTheLoopBasic.csproj" />
+  <Folder Name="/Samples/03-workflows/HumanInTheLoop/">
+    <Project Path="samples/03-workflows/HumanInTheLoop/HumanInTheLoopBasic/HumanInTheLoopBasic.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Observability/">
-    <Project Path="samples/GettingStarted/Workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Observability/AspireDashboard/AspireDashboard.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/Observability/WorkflowAsAnAgent/WorkflowAsAnAgentObservability.csproj" />
+  <Folder Name="/Samples/03-workflows/Observability/">
+    <Project Path="samples/03-workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
+    <Project Path="samples/03-workflows/Observability/AspireDashboard/AspireDashboard.csproj" />
+    <Project Path="samples/03-workflows/Observability/WorkflowAsAnAgent/WorkflowAsAnAgentObservability.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/Visualization/">
-    <Project Path="samples/GettingStarted/Workflows/Visualization/Visualization.csproj" />
+  <Folder Name="/Samples/03-workflows/Visualization/">
+    <Project Path="samples/03-workflows/Visualization/Visualization.csproj" />
  </Folder>
-  <Folder Name="/Samples/GettingStarted/Workflows/_Foundational/">
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/01_ExecutorsAndEdges/01_ExecutorsAndEdges.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/02_Streaming/02_Streaming.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/03_AgentsInWorkflows/03_AgentsInWorkflows.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/04_AgentWorkflowPatterns/04_AgentWorkflowPatterns.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/05_MultiModelService/05_MultiModelService.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/06_SubWorkflows/06_SubWorkflows.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/07_MixedWorkflowAgentsAndExecutors/07_MixedWorkflowAgentsAndExecutors.csproj" />
-    <Project Path="samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/08_WriterCriticWorkflow.csproj" />
+  <Folder Name="/Samples/03-workflows/_StartHere/">
+    <Project Path="samples/03-workflows/_StartHere/01_Streaming/01_Streaming.csproj" />
+    <Project Path="samples/03-workflows/_StartHere/02_AgentsInWorkflows/02_AgentsInWorkflows.csproj" />
+    <Project Path="samples/03-workflows/_StartHere/03_AgentWorkflowPatterns/03_AgentWorkflowPatterns.csproj" />
+    <Project Path="samples/03-workflows/_StartHere/04_MultiModelService/04_MultiModelService.csproj" />
+    <Project Path="samples/03-workflows/_StartHere/05_SubWorkflows/05_SubWorkflows.csproj" />
+    <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/HostedAgents/">
-    <Project Path="samples/HostedAgents/AgentsInWorkflows/AgentsInWorkflows.csproj" />
-    <Project Path="samples/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj" />
-    <Project Path="samples/HostedAgents/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
+  <Folder Name="/Samples/04-hosting/" />
+  <Folder Name="/Samples/04-hosting/DurableAgents/" />
+  <Folder Name="/Samples/04-hosting/DurableAgents/AzureFunctions/">
+    <File Path="samples/04-hosting/DurableAgents/AzureFunctions/.editorconfig" />
+    <File Path="samples/04-hosting/DurableAgents/AzureFunctions/README.md" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/01_SingleAgent/01_SingleAgent.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/06_LongRunningTools/06_LongRunningTools.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/07_AgentAsMcpTool/07_AgentAsMcpTool.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/08_ReliableStreaming/08_ReliableStreaming.csproj" />
  </Folder>
-  <Folder Name="/Samples/M365Agent/">
-    <Project Path="samples/M365Agent/M365Agent.csproj" />
+  <Folder Name="/Samples/04-hosting/DurableAgents/ConsoleApps/">
+    <File Path="samples/04-hosting/DurableAgents/ConsoleApps/README.md" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/01_SingleAgent/01_SingleAgent.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/06_LongRunningTools/06_LongRunningTools.csproj" />
+    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/07_ReliableStreaming/07_ReliableStreaming.csproj" />
+  </Folder>
+  <Folder Name="/Samples/04-hosting/A2A/">
+    <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 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/A2AClientServer/">
+    <File Path="samples/05-end-to-end/A2AClientServer/README.md" />
+    <Project Path="samples/05-end-to-end/A2AClientServer/A2AClient/A2AClient.csproj" />
+    <Project Path="samples/05-end-to-end/A2AClientServer/A2AServer/A2AServer.csproj" />
+  </Folder>
+  <Folder Name="/Samples/05-end-to-end/AgentWebChat/">
+    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.AgentHost/AgentWebChat.AgentHost.csproj" />
+    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.AppHost/AgentWebChat.AppHost.csproj" />
+    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.ServiceDefaults/AgentWebChat.ServiceDefaults.csproj" />
+    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.Web/AgentWebChat.Web.csproj" />
+  </Folder>
+  <Folder Name="/Samples/05-end-to-end/AGUIClientServer/">
+    <File Path="samples/05-end-to-end/AGUIClientServer/README.md" />
+    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIClient/AGUIClient.csproj" />
+    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj" />
+    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIServer/AGUIServer.csproj" />
+  </Folder>
+  <Folder Name="/Samples/05-end-to-end/HostedAgents/">
+    <Project Path="samples/05-end-to-end/HostedAgents/AgentsInWorkflows/AgentsInWorkflows.csproj" />
+    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj" />
+    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
+  </Folder>
+  <Folder Name="/Samples/05-end-to-end/AspNetAgentAuthorization/">
+    <File Path="samples/05-end-to-end/AspNetAgentAuthorization/docker-compose.yml" />
+    <File Path="samples/05-end-to-end/AspNetAgentAuthorization/README.md" />
+    <Project Path="samples/05-end-to-end/AspNetAgentAuthorization/Service/Service.csproj" />
+    <Project Path="samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/RazorWebClient.csproj" />
  </Folder>
  <Folder Name="/Solution Items/">
    <File Path=".editorconfig" />
    <File Path=".gitignore" />
+    <File Path="AGENTS.md" />
    <File Path="Directory.Build.props" />
    <File Path="Directory.Build.targets" />
    <File Path="Directory.Packages.props" />
    <File Path="global.json" />
    <File Path="nuget.config" />
+    <File Path="README.md" />
  </Folder>
  <Folder Name="/Solution Items/.github/" />
  <Folder Name="/Solution Items/.github/upgrades/" />
@@ -312,6 +334,10 @@
    <File Path="../docs/decisions/0012-python-typeddict-options.md" />
    <File Path="../docs/decisions/0013-python-get-response-simplification.md" />
    <File Path="../docs/decisions/0014-feature-collections.md" />
+    <File Path="../docs/decisions/0015-agent-run-context.md" />
+    <File Path="../docs/decisions/0016-python-context-middleware.md" />
+    <File Path="../docs/decisions/0017-agent-additional-properties.md" />
+    <File Path="../docs/decisions/0018-agentthread-serialization.md" />
    <File Path="../docs/decisions/adr-short-template.md" />
    <File Path="../docs/decisions/adr-template.md" />
    <File Path="../docs/decisions/README.md" />
@@ -417,6 +443,7 @@
    <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" />
@@ -428,6 +455,7 @@
    <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.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" />
    <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
@@ -441,6 +469,7 @@
    <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" />
@@ -461,6 +490,7 @@
    <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" />
@@ -471,6 +501,7 @@
    <Project Path="tests/Microsoft.Agents.AI.OpenAI.UnitTests/Microsoft.Agents.AI.OpenAI.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Purview.UnitTests/Microsoft.Agents.AI.Purview.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.UnitTests/Microsoft.Agents.AI.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Workflows.Generators.UnitTests/Microsoft.Agents.AI.Workflows.Generators.UnitTests.csproj" />
    <Project Path="tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj" />
@@ -2,11 +2,11 @@
  <PropertyGroup>
    <!-- Central version prefix - applies to all nuget packages. -->
    <VersionPrefix>1.0.0</VersionPrefix>
-    <RCNumber>1</RCNumber>
+    <RCNumber>3</RCNumber>
    <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260219.1</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260219.1</PackageVersion>
-    <GitTag>1.0.0-rc1</GitTag>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260304.1</PackageVersion>
+    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260304.1</PackageVersion>
+    <GitTag>1.0.0-rc3</GitTag>

    <Configurations>Debug;Release;Publish</Configurations>
    <IsPackable>true</IsPackable>
@@ -15,7 +15,7 @@
  </ItemGroup>

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

 </Project>
@@ -15,7 +15,7 @@
  </ItemGroup>

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

 </Project>
@@ -15,7 +15,7 @@
  </ItemGroup>

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

 </Project>
@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -89,10 +89,10 @@ namespace SampleApp
    internal sealed class UserInfoMemory : AIContextProvider
    {
        private readonly ProviderSessionState<UserInfo> _sessionState;
+        private IReadOnlyList<string>? _stateKeys;
        private readonly IChatClient _chatClient;

        public UserInfoMemory(IChatClient chatClient, Func<AgentSession?, UserInfo>? stateInitializer = null)
-            : base(null, null)
        {
            this._sessionState = new ProviderSessionState<UserInfo>(
                stateInitializer ?? (_ => new UserInfo()),
@@ -100,7 +100,7 @@ namespace SampleApp
            this._chatClient = chatClient;
        }

-        public override string StateKey => this._sessionState.StateKey;
+        public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey];

        public UserInfo GetUserInfo(AgentSession session)
            => this._sessionState.GetOrInitializeState(session);
@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,31 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <!-- The Functions build tools don't like namespaces that start with a number -->
+    <AssemblyName>HostedAgent</AssemblyName>
+    <RootNamespace>HostedAgent</RootNamespace>
+  </PropertyGroup>
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+  <!-- Azure Functions packages -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
+  </ItemGroup>
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to host an AI agent with Azure Functions (DurableAgents).
+//
+// Prerequisites:
+//   - Azure Functions Core Tools
+//   - Azure OpenAI resource
+//
+// Environment variables:
+//   AZURE_OPENAI_ENDPOINT
+//   AZURE_OPENAI_DEPLOYMENT_NAME (defaults to "gpt-4o-mini")
+//
+// Run with: func start
+// Then call: POST http://localhost:7071/api/agents/HostedAgent/run
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hosting.AzureFunctions;
+using Microsoft.Azure.Functions.Worker.Builder;
+using Microsoft.Extensions.Hosting;
+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";
+
+// Set up an AI agent following the standard Microsoft Agent Framework pattern.
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
+    .GetChatClient(deploymentName)
+    .AsAIAgent(
+        instructions: "You are a helpful assistant hosted in Azure Functions.",
+        name: "HostedAgent");
+
+// Configure the function app to host the AI agent.
+// This will automatically generate HTTP API endpoints for the agent.
+using IHost app = FunctionsApplication
+    .CreateBuilder(args)
+    .ConfigureFunctionsWebApplication()
+    .ConfigureDurableAgents(options => options.AddAIAgent(agent, timeToLive: TimeSpan.FromHours(1)))
+    .Build();
+app.Run();
@@ -7,7 +7,7 @@ using Anthropic.Foundry;
 using Azure.Identity;
 using Microsoft.Agents.AI;

-string deploymentName = Environment.GetEnvironmentVariable("ANTHROPIC_DEPLOYMENT_NAME") ?? "claude-haiku-4-5";
+string deploymentName = Environment.GetEnvironmentVariable("ANTHROPIC_CHAT_MODEL_NAME") ?? "claude-haiku-4-5";

 // The resource is the subdomain name / first name coming before '.services.ai.azure.com' in the endpoint Uri
 // ie: https://(resource name).services.ai.azure.com/anthropic/v1/chat/completions
@@ -22,7 +22,7 @@ Set the following environment variables:

 ```powershell
 $env:ANTHROPIC_API_KEY="your-anthropic-api-key"  # Replace with your Anthropic API key
-$env:ANTHROPIC_DEPLOYMENT_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
+$env:ANTHROPIC_CHAT_MODEL_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
 ```

 ### For Azure Foundry with API Key
@@ -35,7 +35,7 @@ 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_API_KEY="your-anthropic-api-key"  # Replace with your Anthropic API key
-$env:ANTHROPIC_DEPLOYMENT_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
+$env:ANTHROPIC_CHAT_MODEL_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
 ```

 ### For Azure Foundry with Azure CLI
@@ -47,7 +47,7 @@ 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_DEPLOYMENT_NAME="claude-haiku-4-5"  # Optional, defaults to claude-haiku-4-5
+$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).
@@ -6,8 +6,8 @@ using Azure.AI.Agents.Persistent;
 using Azure.Identity;
 using Microsoft.Agents.AI;

-var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+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";

 const string JokerName = "Joker";
 const string JokerInstructions = "You are good at telling jokes.";
@@ -21,6 +21,6 @@ Before you begin, ensure you have the following prerequisites:
 Set the following environment variables:

 ```powershell
-$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
-$env:AZURE_FOUNDRY_PROJECT_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 Azure Foundry resource endpoint
+$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
 ```
@@ -7,8 +7,8 @@ using Azure.AI.Projects.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;

-var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+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";

 const string JokerName = "JokerAgent";

@@ -21,6 +21,6 @@ Before you begin, ensure you have the following prerequisites:
 Set the following environment variables:

 ```powershell
-$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
-$env:AZURE_FOUNDRY_PROJECT_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 Azure Foundry resource endpoint
+$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
 ```
@@ -11,9 +11,9 @@ using Microsoft.Agents.AI;
 using OpenAI;
 using OpenAI.Chat;

-var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
-var apiKey = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_API_KEY");
-var model = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_MODEL_DEPLOYMENT") ?? "Phi-4-mini-instruct";
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+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.
 var clientOptions = new OpenAIClientOptions() { Endpoint = new Uri(endpoint) };
@@ -13,7 +13,7 @@ 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,
-so if you want to use a different model, ensure that you set your `AZURE_FOUNDRY_MODEL_DEPLOYMENT` environment
+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

@@ -24,11 +24,11 @@ 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.
-$env:AZURE_FOUNDRY_OPENAI_ENDPOINT="https://ai-foundry-<myresourcename>.services.ai.azure.com/openai/v1/"
+$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
-$env:AZURE_FOUNDRY_OPENAI_API_KEY="************"
+$env:AZURE_OPENAI_API_KEY="************"

 # Optional, defaults to Phi-4-mini-instruct
-$env:AZURE_FOUNDRY_MODEL_DEPLOYMENT="Phi-4-mini-instruct"
+$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="Phi-4-mini-instruct"
 ```
--- a/Show More
+++ b/Show More