Merge branch 'main' into dmkorolev/threads

* a2a + sharepoint samples

* small fixes

.devcontainer/devcontainer.json

@@ -0,0 +1,19 @@
+{
+  "name": "Python 3",
+  "image": "mcr.microsoft.com/devcontainers/python:3.13-bullseye",
+  "features": {
+    "ghcr.io/va-h/devcontainers-features/uv:1": {},
+    "ghcr.io/devcontainers/features/azure-cli:1.2.8": {}
+  },
+  "postCreateCommand": "bash ./devsetup.sh",
+  "workspaceFolder": "/workspaces/agent-framework/python/",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-windows-ai-studio.windows-ai-studio",
+        "littlefoxteam.vscode-python-test-adapter"
+      ]
+    }
+  }
+}

.devcontainer/dotnet/devcontainer.json

@@ -0,0 +1,19 @@
+{
+  "name": "C# (.NET)",
+  "image": "mcr.microsoft.com/devcontainers/dotnet:9.0",
+  "features": {
+    "ghcr.io/devcontainers/features/dotnet:2.4.0": {},
+    "ghcr.io/devcontainers/features/powershell:1.5.1": {},
+    "ghcr.io/devcontainers/features/azure-cli:1.2.8": {}
+  },
+  "workspaceFolder": "/workspaces/agent-framework/dotnet/",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-dotnettools.csdevkit",
+        "vscode-icons-team.vscode-icons",
+        "ms-windows-ai-studio.windows-ai-studio"
+      ]
+    }
+  }
+}

.gitattributes

@@ -1,6 +1,5 @@
 # Auto-detect text files, ensure they use LF.
 * text=auto eol=lf working-tree-encoding=UTF-8
-
 # Bash scripts
 *.sh  text eol=lf
-*.cmd text eol=crlf
+*.cmd text eol=crlf

.github/.linkspector.yml

@@ -0,0 +1,32 @@
+dirs:
+  - .
+excludedFiles:
+  - ./python/CHANGELOG.md
+ignorePatterns:
+  - pattern: "/github/"
+  - pattern: "./actions"
+  - pattern: "./blob"
+  - pattern: "./issues"
+  - pattern: "./discussions"
+  - pattern: "./pulls"
+  - pattern: "https:\/\/platform.openai.com"
+  - pattern: "http:\/\/localhost"
+  - pattern: "http:\/\/127.0.0.1"
+  - pattern: "https:\/\/localhost"
+  - pattern: "https:\/\/127.0.0.1"
+  - pattern: "0001-spec.md"
+  - pattern: "0001-madr-architecture-decisions.md"
+  - pattern: "https://api.powerplatform.com/.default"
+  - pattern: "https://your-resource.openai.azure.com/"
+  - pattern: "http://host.docker.internal"
+  - pattern: "https://openai.github.io/openai-agents-js/openai/agents/classes/"
+# excludedDirs:
+  # Folders which include links to localhost, since it's not ignored with regular expressions
+baseUrl: https://github.com/microsoft/agent-framework/
+aliveStatusCodes:
+  - 200
+  - 206
+  - 429
+  - 500
+  - 503
+useGitIgnore: true

.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Code ownership assignments
+# https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+python/packages/azurefunctions/ @microsoft/agentframework-durabletask-developers

.github/actions/azure-functions-integration-setup/action.yml

@@ -0,0 +1,36 @@
+name: Azure Functions Integration Test Setup
+description: Prepare local emulators and tools for Azure Functions integration tests
+
+runs:
+    using: "composite"
+    steps:
+      - name: Start Durable Task Scheduler Emulator
+        shell: bash
+        run: |
+          if [ "$(docker ps -aq -f name=dts-emulator)" ]; then
+            echo "Stopping and removing existing Durable Task Scheduler Emulator"
+            docker rm -f dts-emulator
+          fi
+          echo "Starting Durable Task Scheduler Emulator"
+          docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest
+          echo "Waiting for Durable Task Scheduler Emulator to be ready"
+          timeout 30 bash -c 'until curl --silent http://localhost:8080/healthz; do sleep 1; done'
+          echo "Durable Task Scheduler Emulator is ready"
+      - name: Start Azurite (Azure Storage emulator)
+        shell: bash
+        run: |
+          if [ "$(docker ps -aq -f name=azurite)" ]; then
+            echo "Stopping and removing existing Azurite (Azure Storage emulator)"
+            docker rm -f azurite
+          fi
+          echo "Starting Azurite (Azure Storage emulator)"
+          docker run -d --name azurite -p 10000:10000 -p 10001:10001 -p 10002:10002 mcr.microsoft.com/azure-storage/azurite
+          echo "Waiting for Azurite (Azure Storage emulator) to be ready"
+          timeout 30 bash -c 'until curl --silent http://localhost:10000/devstoreaccount1; do sleep 1; done'
+          echo "Azurite (Azure Storage emulator) is ready"
+      - name: Install Azure Functions Core Tools
+        shell: bash
+        run: |
+          echo "Installing Azure Functions Core Tools"
+          npm install -g azure-functions-core-tools@4 --unsafe-perm true
+          func --version

.github/actions/python-setup/action.yml

@@ -0,0 +1,25 @@
+name: Reusable Setup UV
+description: Reusable workflow to setup uv environment
+
+inputs:
+    python-version:
+      description: The Python version to set up
+      required: true
+    os:
+      description: The operating system to set up
+      required: true
+
+runs:
+    using: "composite"
+    steps:
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+        with:
+            version-file: "python/pyproject.toml"
+            enable-cache: true
+            cache-suffix: ${{ inputs.os }}-${{ inputs.python-version }}
+            cache-dependency-glob: "**/uv.lock"
+      - name: Install the project
+        shell: bash
+        run: |
+          cd python && uv sync --all-packages --all-extras --dev -U --prerelease=if-necessary-or-explicit

.github/copilot-instructions.md

@@ -0,0 +1,67 @@
+# GitHub Copilot Instructions
+
+This repository contains both Python and C# code.
+All python code resides under the `python/` directory.
+All C# code resides under the `dotnet/` directory.
+
+The purpose of the code is to provide a framework for building AI agents.
+
+When contributing to this repository, please follow these guidelines:
+
+## C# Code Guidelines
+
+Here are some general guidelines that apply to all code.
+
+- The top of all *.cs files should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.`
+- All public methods and classes should have XML documentation comments.
+
+### C# Sample Code Guidelines
+
+Sample code is located in the `dotnet/samples` directory.
+
+When adding a new sample, follow these steps:
+
+- The sample should be a standalone .net project in one of the subdirectories of the samples directory.
+- The directory name should be the same as the project name.
+- The directory should contain a README.md file that explains what the sample does and how to run it.
+- The README.md file should follow the same format as other samples.
+- The csproj file should match the directory name.
+- The csproj file should be configured in the same way as other samples.
+- The project should preferably contain a single Program.cs file that contains all the sample code.
+- The sample should be added to the solution file in the samples directory.
+- The sample should be tested to ensure it works as expected.
+- A reference to the new samples should be added to the README.md file in the parent directory of the new sample.
+
+The sample code should follow these guidelines:
+
+- Configuration settings should be read from environment variables, e.g. `var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");`.
+- Environment variables should use upper snake_case naming convention.
+- Secrets should not be hardcoded in the code or committed to the repository.
+- The code should be well-documented with comments explaining the purpose of each step.
+- The code should be simple and to the point, avoiding unnecessary complexity.
+- Prefer inline literals over constants for values that are not reused. For example, use `new ChatClientAgent(chatClient, instructions: "You are a helpful assistant.")` instead of defining a constant for "instructions".
+- Ensure that all private classes are sealed
+- Use the Async suffix on the name of all async methods that return a Task or ValueTask.
+- Prefer defining variables using types rather than var, to help users understand the types involved.
+- Follow the patterns in the samples in the same directories where new samples are being added.
+- The structure of the sample should be as follows:
+  - The top of the Program.cs should have a copyright notice: `// Copyright (c) Microsoft. All rights reserved.`
+  - Then add a comment describing what the sample is demonstrating.
+  - Then add the necessary using statements.
+  - Then add the main code logic.
+  - Finally, add any helper methods or classes at the bottom of the file.
+
+### C# Unit Test Guidelines
+
+Unit tests are located in the `dotnet/tests` directory in projects with a `.UnitTests.csproj` suffix.
+
+Unit tests should follow these guidelines:
+
+- Use `this.` for accessing class members
+- Add Arrange, Act and Assert comments for each test
+- Ensure that all private classes, that are not subclassed, are sealed
+- Use the Async suffix on the name of all async methods
+- Use the Moq library for mocking objects where possible
+- Validate that each test actually tests the target behavior, e.g. we should not have tests that creates a mock, calls the mock and then verifies that the mock was called, without the target code being involved. We also shouldn't have tests that test language features, e.g. something that the compiler would catch anyway.
+- Avoid adding excessive comments to tests. Instead favour clear easy to understand code.
+- Follow the patterns in the unit tests in the same project or classes to which new tests are being added

.github/dependabot.yml

@@ -11,9 +11,6 @@ updates:
     schedule:
       interval: "cron"
       cronjob: "0 8 * * 4,0" # Every Thursday(4) and Sunday(0) at 8:00 UTC
-    experimental:  
-      nuget-native-updater: false
-      enable-cooldown-metrics-collection: false
     ignore:
       # For all System.* and Microsoft.Extensions/Bcl.* packages, ignore all major version updates
       - dependency-name: "System.*"
@@ -27,7 +24,7 @@ updates:
       - ".NET"
       - "dependencies"
 
-  # Maintain dependencies for pip
+  # Maintain dependencies for python
   - package-ecosystem: "pip"
     directory: "python/"
     schedule:
@@ -36,6 +33,14 @@ updates:
     labels:
       - "python"
       - "dependencies"
+  - package-ecosystem: "uv"
+    directory: "python/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    labels:
+      - "python"
+      - "dependencies"
 
   # Maintain dependencies for github-actions
   - package-ecosystem: "github-actions"

.github/labeler.yml

@@ -16,3 +16,19 @@ documentation:
   - any-glob-to-any-file:
     - docs/**
     - '**/*.md'
+
+# Add 'workflows' label to any change within the dotnet or python workflows src or samples
+workflows:
+- changed-files:
+  - any-glob-to-any-file:
+    - dotnet/src/Microsoft.Agents.AI.Workflows/**
+    - dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/**
+    - dotnet/samples/GettingStarted/Workflow/**
+    - python/packages/main/agent_framework/_workflow/**
+    - python/samples/getting_started/workflow/**
+
+# Add 'lab' label to any change within the 'python/packages/lab' directory
+lab:
+- changed-files:
+  - any-glob-to-any-file:
+    - python/packages/lab/**

.github/pull_request_template.md

@@ -20,4 +20,4 @@ Please help reviewers and future users, providing the following information:
 - [ ] The code builds clean without any errors or warnings
 - [ ] The PR follows the [Contribution Guidelines](https://github.com/microsoft/agent-framework/blob/main/CONTRIBUTING.md)
 - [ ] All unit tests pass, and I have added new tests where possible
-- [ ] I didn't break anyone :smile:
+- [ ] **Is this a breaking change?** If yes, add "[BREAKING]" prefix to the title of the PR.

.github/workflows/codeql-analysis.yml

@@ -32,13 +32,13 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v3
+        uses: github/codeql-action/init@v4
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -51,7 +51,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v3
+        uses: github/codeql-action/autobuild@v4
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
@@ -64,6 +64,6 @@ jobs:
       #     ./location_of_script_within_repo/buildscript.sh
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3
+        uses: github/codeql-action/analyze@v4
         with:
           category: "/language:${{matrix.language}}"

.github/workflows/dotnet-build-and-test.yml

@@ -9,16 +9,10 @@ on:
   workflow_dispatch:
   pull_request:
     branches: ["main", "feature*"]
-    paths:
-      - dotnet/**
-      - '.github/workflows/dotnet-build-and-test.yml'
   merge_group:
-    branches: ["main"]
+    branches: ["main", "feature*"]
   push:
     branches: ["main", "feature*"]
-    paths:
-      - dotnet/**
-      - '.github/workflows/dotnet-build-and-test.yml'
   schedule:
     - cron: "0 0 * * *" # Run at midnight UTC daily
 
@@ -34,7 +28,33 @@ permissions:
   id-token: "write"
 
 jobs:
+  paths-filter:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      dotnetChanges: ${{ steps.filter.outputs.dotnet}}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            dotnet:
+              - 'dotnet/**'
+      # run only if 'dotnet' files were changed
+      - name: dotnet tests
+        if: steps.filter.outputs.dotnet == 'true'
+        run: echo "Dotnet file"
+      # run only if not 'dotnet' files were changed
+      - name: not dotnet tests
+        if: steps.filter.outputs.dotnet != 'true'
+        run: echo "NOT dotnet file"
+
   dotnet-build-and-test:
+    needs: paths-filter
+    if: needs.paths-filter.outputs.dotnetChanges == 'true'
     strategy:
       fail-fast: false
       matrix:
@@ -47,15 +67,18 @@ jobs:
     runs-on: ${{ matrix.os }}
     environment: ${{ matrix.environment }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           persist-credentials: false
           sparse-checkout: |
             .
             .github
             dotnet
+            python
+            workflow-samples
+
       - name: Setup dotnet
-        uses: actions/setup-dotnet@v4.3.1
+        uses: actions/setup-dotnet@v5.0.0
         with:
           global-json-file: ${{ github.workspace }}/dotnet/global.json
       - name: Build dotnet solutions
@@ -92,7 +115,7 @@ jobs:
 
           # Change to project directory to ensure local nuget.config is used
           pushd consoleapp
-          dotnet add packcheck.csproj package Microsoft.Extensions.AI.Agents --prerelease
+          dotnet add packcheck.csproj package Microsoft.Agents.AI --prerelease
           dotnet build -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} packcheck.csproj
 
           # Clean up
@@ -105,7 +128,15 @@ jobs:
         run: |
           export UT_PROJECTS=$(find ./dotnet -type f -name "*.UnitTests.csproj" | tr '\n' ' ')
           for project in $UT_PROJECTS; do
-            dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx --collect:"XPlat Code Coverage" --results-directory:"TestResults/Coverage/" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.ExcludeByAttribute=GeneratedCodeAttribute,CompilerGeneratedAttribute,ExcludeFromCodeCoverageAttribute
+            # Query the project's target frameworks using MSBuild with the current configuration
+            target_frameworks=$(dotnet msbuild $project -getProperty:TargetFrameworks -p:Configuration=${{ matrix.configuration }} -nologo 2>/dev/null | tr -d '\r')
+            
+            # Check if the project supports the target framework
+            if [[ "$target_frameworks" == *"${{ matrix.targetFramework }}"* ]]; then
+              dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx --collect:"XPlat Code Coverage" --results-directory:"TestResults/Coverage/" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.ExcludeByAttribute=GeneratedCodeAttribute,CompilerGeneratedAttribute,ExcludeFromCodeCoverageAttribute
+            else
+              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
+            fi
           done
       
       - name: Log event name and matrix integration-tests
@@ -120,33 +151,57 @@ jobs:
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
 
+        # This setup action is required for both Durable Task and Azure Functions integration tests.
+        # We only run it on Ubuntu since the Durable Task and Azure Functions features are not available
+        # on .NET Framework (net472) which is what we use the Windows runner for.
+      - name: Set up Durable Task and Azure Functions Integration Test Emulators
+        if: github.event_name != 'pull_request' && matrix.integration-tests && matrix.os == 'ubuntu-latest'
+        uses: ./.github/actions/azure-functions-integration-setup
+        id: azure-functions-setup
+
       - name: Run Integration Tests
         shell: bash
         if: github.event_name != 'pull_request' && matrix.integration-tests
         run: |
           export INTEGRATION_TEST_PROJECTS=$(find ./dotnet -type f -name "*IntegrationTests.csproj" | tr '\n' ' ')
           for project in $INTEGRATION_TEST_PROJECTS; do
-            dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx
+            # Query the project's target frameworks using MSBuild with the current configuration
+            target_frameworks=$(dotnet msbuild $project -getProperty:TargetFrameworks -p:Configuration=${{ matrix.configuration }} -nologo 2>/dev/null | tr -d '\r')
+            
+            # Check if the project supports the target framework
+            if [[ "$target_frameworks" == *"${{ matrix.targetFramework }}"* ]]; then
+              dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx
+            else
+              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
+            fi
           done
         env:
           # OpenAI Models
           OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
           OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
           OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}
+          # Azure OpenAI Models
+          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__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 }}
 
       # Generate test reports and check coverage
       - name: Generate test reports
-        uses: danielpalme/ReportGenerator-GitHub-Action@5.4.10
+        uses: danielpalme/ReportGenerator-GitHub-Action@5.4.18
         with:
           reports: "./TestResults/Coverage/**/coverage.cobertura.xml"
           targetdir: "./TestResults/Reports"
           reporttypes: "HtmlInline;JsonSummary"
 
       - name: Upload coverage report artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: CoverageReport-${{ matrix.os }}-${{ matrix.targetFramework }}-${{ matrix.configuration }} # Artifact name
           path: ./TestResults/Reports # Directory containing files to upload
@@ -187,13 +242,13 @@ jobs:
       - name: Fail workflow if tests failed
         id: check_tests_failed
         if: contains(join(needs.*.result, ','), 'failure')
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: core.setFailed('Integration Tests Failed!')
 
       - name: Fail workflow if tests cancelled
         id: check_tests_cancelled
         if: contains(join(needs.*.result, ','), 'cancelled')
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: core.setFailed('Integration Tests Cancelled!')

.github/workflows/dotnet-check-coverage.ps1

@@ -9,8 +9,8 @@ $coverageBelowThreshold = $false
 $nonExperimentalAssemblies = [System.Collections.Generic.HashSet[string]]::new()
 
 $assembliesCollection = @(
-    'Microsoft.Extensions.AI.Agents.Abstractions'
-    'Microsoft.Extensions.AI.Agents'
+    'Microsoft.Agents.AI.Abstractions'
+    'Microsoft.Agents.AI'
 )
 
 foreach ($assembly in $assembliesCollection) {

.github/workflows/dotnet-format.yml

@@ -30,7 +30,7 @@ jobs:
 
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -86,10 +86,11 @@ jobs:
         run: docker pull mcr.microsoft.com/dotnet/sdk:${{ matrix.dotnet }}
 
       # This step will run dotnet format on each of the unique csproj files and fail if any changes are made
+      # exclude-diagnostics should be removed after fixes for IL2026 and IL3050 are out: https://github.com/dotnet/sdk/issues/51136
       - name: Run dotnet format
         if: steps.find-csproj.outputs.csproj_files != ''
         run: |
           for csproj in ${{ steps.find-csproj.outputs.csproj_files }}; do
             echo "Running dotnet format on $csproj"
-            docker run --rm -v $(pwd):/app -w /app mcr.microsoft.com/dotnet/sdk:${{ matrix.dotnet }} /bin/sh -c "dotnet format $csproj --verify-no-changes --verbosity diagnostic"
+            docker run --rm -v $(pwd):/app -w /app mcr.microsoft.com/dotnet/sdk:${{ matrix.dotnet }} /bin/sh -c "dotnet format $csproj --verify-no-changes --verbosity diagnostic --exclude-diagnostics IL2026 IL3050"
           done

.github/workflows/label-issues.yml

@@ -13,7 +13,7 @@ jobs:
     permissions:
       issues: write
     steps:
-      - uses: actions/github-script@v7
+      - uses: actions/github-script@v8
         with:
           github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
           script: |
@@ -22,7 +22,28 @@ jobs:
             let title = context.payload.issue.title
 
             // Define the labels array
-            let labels = ["triage"]
+            let labels = []
+
+            // Check if the issue author is in the agentframework-developers team
+            let isTeamMember = false
+            try {
+              const teamMembership = await github.rest.teams.getMembershipForUserInOrg({
+                org: context.repo.owner,
+                team_slug: process.env.TEAM_NAME,
+                username: context.payload.issue.user.login
+              })
+              console.log("Team Membership Data:", teamMembership);
+              isTeamMember = teamMembership.data.state === 'active'
+            } catch (error) {
+              // User is not in the team or team doesn't exist
+              console.error("Error fetching team membership:", error);
+              isTeamMember = false
+            }
+
+            // Only add triage label if the author is not in the team
+            if (!isTeamMember) {
+              labels.push("triage")
+            }
 
             // Check if the body or the title contains the word 'python' (case-insensitive)
             if ((body != null && body.match(/python/i)) || (title != null && title.match(/python/i))) {
@@ -39,10 +60,14 @@ jobs:
               labels.push(".NET")
             }
 
-            // Add the labels to the issue
-            github.rest.issues.addLabels({
-              issue_number: context.issue.number,
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              labels: labels
-            });
+            // Add the labels to the issue (only if there are labels to add)
+            if (labels.length > 0) {
+              github.rest.issues.addLabels({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                labels: labels
+              });
+            }
+        env:
+          TEAM_NAME: ${{ secrets.DEVELOPER_TEAM }}

.github/workflows/label-pr.yml

@@ -16,6 +16,6 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/labeler@v5
+      - uses: actions/labeler@v6
         with:
           repo-token: "${{ secrets.GH_ACTIONS_PR_WRITE }}"

.github/workflows/label-title-prefix.yml

@@ -15,7 +15,7 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/github-script@v7
+      - uses: actions/github-script@v8
         name: "Issue/PR: update title"
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/markdown-link-check.yml

@@ -0,0 +1,33 @@
+name: Check .md links
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: ["main"]
+    paths:
+      - '**.md'
+      - '.github/workflows/markdown-link-check.yml'
+      - '.github/.linkspector.yml'
+  schedule:
+    - cron: "0 0 * * *" # Run at midnight UTC daily
+
+permissions:
+  contents: read
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-22.04
+    # check out the latest version of the code
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      # Checks the status of hyperlinks in all files
+      - name: Run linkspector
+        uses: umbrelladocs/action-linkspector@v1
+        with:
+          reporter: local
+          filter_mode: nofilter
+          fail_on_error: true
+          config_file: ".github/.linkspector.yml"

.github/workflows/python-code-quality.yml

@@ -8,7 +8,8 @@ on:
       - "python/**"
 
 env:
-  UV_SEMVER: "0.8.x"
+  # Configure a constant location for the uv cache
+  UV_CACHE_DIR: /tmp/.uv-cache
 
 jobs:
   pre-commit:
@@ -17,28 +18,28 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.10", "3.14"]
     runs-on: ubuntu-latest
     continue-on-error: true
     defaults:
       run:
         working-directory: ./python
     env:
-      # Configure a constant location for the uv cache
-      UV_CACHE_DIR: /tmp/.uv-cache
       UV_PYTHON: ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v5
         with:
-          version: ${{ env.UV_SEMVER }}
-          enable-cache: true
-          cache-suffix: ${{ runner.os }}-${{ matrix.python-version }}
-          cache-dependency-glob: "**/uv.lock"
-      - name: Install the project
-        run: uv sync --all-extras --dev
-      - uses: actions/cache@v3
+          fetch-depth: 0
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          # Configure a constant location for the uv cache
+          UV_CACHE_DIR: /tmp/.uv-cache
+      - uses: actions/cache@v4
         with:
           path: ~/.cache/pre-commit
           key: pre-commit|${{ matrix.python-version }}|${{ hashFiles('python/.pre-commit-config.yaml') }}
@@ -47,4 +48,6 @@ jobs:
         with:
           extra_args: --config python/.pre-commit-config.yaml --all-files
       - name: Run Mypy
-        run: uv run poe mypy
+        env:
+          GITHUB_BASE_REF: ${{ github.event.pull_request.base.ref || github.base_ref || 'main' }}
+        run: uv run poe ci-mypy

.github/workflows/python-docs.yml

@@ -0,0 +1,39 @@
+name: Python - Create Docs
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+  id-token: write
+env:
+  # Configure a constant location for the uv cache
+  UV_CACHE_DIR: /tmp/.uv-cache
+
+jobs:
+  python-build-docs:
+    if: github.event_name == 'release' && startsWith(github.event.release.tag_name, 'python-')
+    name: Python Build Docs
+    runs-on: ubuntu-latest
+    environment: "integration"
+    env:
+      UV_PYTHON: "3.11"
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version-file: "python/pyproject.toml"
+          enable-cache: true
+          cache-suffix: ${{ runner.os }}-${{ env.UV_PYTHON }}
+          cache-dependency-glob: "**/uv.lock"
+      - name: Install dependencies
+        run: uv sync --all-packages --dev --docs
+      - name: Build the docs
+        run: uv run poe docs-full
+    #  Upload docs to learn gh

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

@@ -0,0 +1,99 @@
+name: Python - Lab Tests
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "python/packages/lab/**"
+  merge_group:
+    branches: ["main"]
+  schedule:
+    - cron: "0 0 * * *" # Run at midnight UTC daily
+
+env:
+  # Configure a constant location for the uv cache
+  UV_CACHE_DIR: /tmp/.uv-cache
+
+jobs:
+  paths-filter:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      pythonChanges: ${{ steps.filter.outputs.python}}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            python:
+              - 'python/**'
+      # run only if 'python' files were changed
+      - name: python tests
+        if: steps.filter.outputs.python == 'true'
+        run: echo "Python file"
+      # run only if not 'python' files were changed
+      - name: not python tests
+        if: steps.filter.outputs.python != 'true'
+        run: echo "NOT python file"
+
+  python-lab-tests:
+    name: Python Lab Tests
+    needs: paths-filter
+    if: needs.paths-filter.outputs.pythonChanges == 'true'
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        # TODO(ekzhu): re-enable macos-latest when this is fixed: https://github.com/actions/runner-images/issues/11881
+        os: [ubuntu-latest, windows-latest]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    permissions:
+      contents: read
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          # Configure a constant location for the uv cache
+          UV_CACHE_DIR: /tmp/.uv-cache
+
+      # Lab specific tests
+      - name: Run lab tests
+        run: cd packages/lab && uv run poe test
+
+      - name: Run lab lint
+        run: cd packages/lab && uv run poe lint
+
+      - name: Run lab format check
+        run: cd packages/lab && uv run poe fmt --check
+
+      - name: Run lab type checking
+        run: cd packages/lab && uv run poe pyright
+
+      - name: Run lab mypy
+        run: cd packages/lab && uv run poe mypy
+
+      # Surface failing tests
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/packages/lab/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Lab Test Results

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

@@ -17,7 +17,7 @@ env:
   # Configure a constant location for the uv cache
   UV_CACHE_DIR: /tmp/.uv-cache
   RUN_INTEGRATION_TESTS: "true"
-  UV_SEMVER: "0.8.x"
+  RUN_SAMPLES_TESTS: ${{ vars.RUN_SAMPLES_TESTS }}
 
 jobs:
   paths-filter:
@@ -28,7 +28,7 @@ jobs:
     outputs:
       pythonChanges: ${{ steps.filter.outputs.python}}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: dorny/paths-filter@v3
         id: filter
         with:
@@ -43,8 +43,8 @@ jobs:
       - name: not python tests
         if: steps.filter.outputs.python != 'true'
         run: echo "NOT python file"
-  python-tests-main:
-    name: Python Tests - Main
+  python-tests-core:
+    name: Python Tests - Core
     needs: paths-filter
     if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
     runs-on: ${{ matrix.os }}
@@ -58,77 +58,33 @@ jobs:
     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 }}
-      PACKAGE_NAME: "main"
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v6
-        with:
-          version: ${{ env.UV_SEMVER }}
-          enable-cache: true
-          cache-suffix: ${{ runner.os }}-${{ matrix.python-version }}
-          cache-dependency-glob: "**/uv.lock"
-      - name: Install the project
-        run: |
-          uv sync --all-packages --all-extras --dev -U --prerelease=if-necessary-or-explicit
-      - name: Test with pytest
-        run: uv run poe --directory ./packages/${{ env.PACKAGE_NAME }} test --junitxml=coverage.xml
-        working-directory: ./python
-      - name: Move coverage file
-        run: |
-          mv ./packages/${{ env.PACKAGE_NAME }}/coverage.xml coverage_${{ env.PACKAGE_NAME }}.xml
-        working-directory: ./python
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-${{ env.PACKAGE_NAME }}
-          path: ./python/coverage_${{ env.PACKAGE_NAME }}.xml
-      - 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: true
-          title: Test results
-
-  python-tests-azure:
-    name: Python Tests - Azure
-    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 }}
+      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_ENDPOINT: ${{ secrets.AZUREOPENAI__ENDPOINT }}
-      PACKAGE_NAME: "azure"
+      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"
+
     defaults:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v5
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
         with:
-          version: ${{ env.UV_SEMVER }}
-          enable-cache: true
-          cache-suffix: ${{ runner.os }}-${{ matrix.python-version }}
-          cache-dependency-glob: "**/uv.lock"
-      - name: Install the project
-        run: |
-          uv sync --all-packages --all-extras --dev -U --prerelease=if-necessary-or-explicit
+          python-version: ${{ matrix.python-version }}
+          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
@@ -136,18 +92,18 @@ jobs:
           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
-        run: uv run poe --directory ./packages/${{ env.PACKAGE_NAME }} test --junitxml=coverage.xml
+        timeout-minutes: 10
+        run: uv run poe all-tests -n logical --dist loadfile --dist worksteal --timeout 300 --retries 3 --retry-delay 10
         working-directory: ./python
-      - name: Move coverage file
-        run: |
-          mv ./packages/${{ env.PACKAGE_NAME }}/coverage.xml coverage_${{ env.PACKAGE_NAME }}.xml
+      - name: Test core samples
+        timeout-minutes: 10
+        if: env.RUN_SAMPLES_TESTS == 'true'
+        run: uv run pytest tests/samples/ -m "openai" -m "azure"
         working-directory: ./python
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-${{ env.PACKAGE_NAME }}
-          path: ./python/coverage_${{ env.PACKAGE_NAME }}.xml
       - name: Surface failing tests
         if: always()
         uses: pmeier/pytest-results-action@v0.7.2
@@ -155,11 +111,11 @@ jobs:
           path: ./python/**.xml
           summary: true
           display-options: fEX
-          fail-on-empty: true
+          fail-on-empty: false
           title: Test results
 
-  python-tests-foundry:
-    name: Python Tests - Foundry
+  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 }}
@@ -172,24 +128,23 @@ jobs:
         environment: ["integration"]
     env:
       UV_PYTHON: ${{ matrix.python-version }}
-      FOUNDRY_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
-      FOUNDRY_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
-      PACKAGE_NAME: "foundry"
+      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@v4
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v5
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
         with:
-          version: ${{ env.UV_SEMVER }}
-          enable-cache: true
-          cache-suffix: ${{ runner.os }}-${{ matrix.python-version }}
-          cache-dependency-glob: "**/uv.lock"
-      - name: Install the project
-        run: |
-          uv sync --all-packages --all-extras --dev -U --prerelease=if-necessary-or-explicit
+          python-version: ${{ matrix.python-version }}
+          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
@@ -198,17 +153,14 @@ jobs:
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
       - name: Test with pytest
-        run: uv run poe --directory ./packages/${{ env.PACKAGE_NAME }} test --junitxml=coverage.xml
+        timeout-minutes: 10
+        run: uv run poe azure-ai-tests -n logical --dist loadfile --dist worksteal --timeout 300 --retries 3 --retry-delay 10
         working-directory: ./python
-      - name: Move coverage file
-        run: |
-          mv ./packages/${{ env.PACKAGE_NAME }}/coverage.xml coverage_${{ env.PACKAGE_NAME }}.xml
+      - name: Test Azure AI samples
+        timeout-minutes: 10
+        if: env.RUN_SAMPLES_TESTS == 'true'
+        run: uv run pytest tests/samples/ -m "azure-ai"
         working-directory: ./python
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-${{ env.PACKAGE_NAME }}
-          path: ./python/coverage_${{ env.PACKAGE_NAME }}.xml
       - name: Surface failing tests
         if: always()
         uses: pmeier/pytest-results-action@v0.7.2
@@ -216,29 +168,31 @@ jobs:
           path: ./python/**.xml
           summary: true
           display-options: fEX
-          fail-on-empty: true
+          fail-on-empty: false
           title: Test results
+
+  # TODO: Add python-tests-lab
+
   python-integration-tests-check:
     if: always()
     runs-on: ubuntu-latest
     needs:
       [
-        python-tests-main,
-        python-tests-azure,
-        python-tests-foundry
+        python-tests-core,
+        python-tests-azure-ai
       ]
     steps:
 
       - name: Fail workflow if tests failed
         id: check_tests_failed
         if: contains(join(needs.*.result, ','), 'failure')
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: core.setFailed('Integration Tests Failed!')
 
       - name: Fail workflow if tests cancelled
         id: check_tests_cancelled
         if: contains(join(needs.*.result, ','), 'cancelled')
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: core.setFailed('Integration Tests Cancelled!')

.github/workflows/python-release.yml

@@ -7,9 +7,9 @@ on:
 permissions:
   contents: write
   id-token: write
-
 env:
-  UV_SEMVER: "0.8.x"
+  # Configure a constant location for the uv cache
+  UV_CACHE_DIR: /tmp/.uv-cache
 
 jobs:
   python-build-assets:
@@ -23,14 +23,16 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v5
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
         with:
-          version: ${{ env.UV_SEMVER }}
-          enable-cache: true
-          cache-suffix: ${{ runner.os }}-${{ env.UV_PYTHON }}
-          cache-dependency-glob: "**/uv.lock"
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          # Configure a constant location for the uv cache
+          UV_CACHE_DIR: /tmp/.uv-cache
       - name: Set environment variables
         run: |
           # Extract package name from tag (format: python-<package>-<version>)

.github/workflows/python-test-coverage-report.yml

@@ -0,0 +1,52 @@
+name: Python - Test Coverage Report
+
+on:
+  workflow_run:
+    workflows: ["Python - Test Coverage"]
+    types:
+      - completed
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  python-test-coverage-report:
+    runs-on: ubuntu-latest
+    if: github.event.workflow_run.conclusion == 'success'
+    continue-on-error: false
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v5
+      - name: Download coverage report
+        uses: actions/download-artifact@v6
+        with:
+          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
+          run-id: ${{ github.event.workflow_run.id }}
+          path: ./python
+          merge-multiple: true
+      - name: Display structure of downloaded files
+        run: ls
+      - name: Read and set PR number
+        # Need to read the PR number from the file saved in the previous workflow
+        # because the workflow_run event does not have access to the PR number
+        # The PR number is needed to post the comment on the PR
+        run: |
+          PR_NUMBER=$(cat pr_number)
+          echo "PR number: $PR_NUMBER"
+          echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
+      - name: Pytest coverage comment
+        id: coverageComment
+        uses: MishaKav/pytest-coverage-comment@v1.1.59
+        with:
+          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
+          issue-number: ${{ env.PR_NUMBER }}
+          pytest-xml-coverage-path: python/python-coverage.xml
+          title: "Python Test Coverage Report"
+          badge-title: "Python Test Coverage"
+          junitxml-title: "Python Unit Test Overview"
+          junitxml-path: python/pytest.xml
+          default-branch: "main"
+          report-only-changed-files: true

.github/workflows/python-test-coverage.yml

@@ -0,0 +1,49 @@
+name: Python - Test Coverage
+
+on:
+  pull_request:
+    branches: ["main", "feature*"]
+    paths:
+      - "python/packages/**"
+      - "python/tests/unit/**"
+env:
+  # Configure a constant location for the uv cache
+  UV_CACHE_DIR: /tmp/.uv-cache
+
+jobs:
+  python-tests-coverage:
+    runs-on: ubuntu-latest
+    continue-on-error: false
+    defaults:
+      run:
+        working-directory: python
+    env:
+      UV_PYTHON: "3.10"
+    steps:
+      - uses: actions/checkout@v5
+      # Save the PR number to a file since the workflow_run event
+      # in the coverage report workflow does not have access to it
+      - name: Save PR number
+        run: |
+          echo ${{ github.event.number }} > ./pr_number
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          # Configure a constant location for the uv cache
+          UV_CACHE_DIR: /tmp/.uv-cache
+      - name: Run all tests with coverage report
+        run: uv run poe all-tests-cov --cov-report=xml:python-coverage.xml -q --junitxml=pytest.xml
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v5
+        with:
+          path: |
+            python/python-coverage.xml
+            python/pytest.xml
+            python/pr_number
+          overwrite: true
+          retention-days: 1
+          if-no-files-found: error

.github/workflows/python-tests.yml

@@ -8,7 +8,6 @@ on:
 env:
   # Configure a constant location for the uv cache
   UV_CACHE_DIR: /tmp/.uv-cache
-  UV_SEMVER: "0.8.x"
 
 jobs:
   python-tests:
@@ -17,8 +16,9 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
-        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+        # todo: add macos-latest when problems are resolved
+        os: [ubuntu-latest, windows-latest]
     env:
       UV_PYTHON: ${{ matrix.python-version }}
     permissions:
@@ -27,80 +27,22 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v5
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
         with:
-          version: ${{ env.UV_SEMVER }}
-          enable-cache: true
-          cache-suffix: ${{ runner.os }}-${{ matrix.python-version }}
-          cache-dependency-glob: "**/uv.lock"
-      - name: Install the project
-        run: |
-          uv sync --all-packages --all-extras --dev -U --prerelease=if-necessary-or-explicit
-      # Main package tests
-      - name: Set environment variables - main - win
-        if: ${{ matrix.os == 'windows-latest' }}
-        run: |
-          echo "PACKAGE_NAME=main" | Out-File -FilePath $env:GITHUB_ENV -Append
-      - name: Set environment variables - main
-        if: ${{ matrix.os != 'windows-latest' }}
-        run: |
-          echo "PACKAGE_NAME=main" >> $GITHUB_ENV
-      - name: Test with pytest - main
-        run: uv run poe --directory ./packages/${{ env.PACKAGE_NAME }} test --junitxml=coverage.xml
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          # Configure a constant location for the uv cache
+          UV_CACHE_DIR: /tmp/.uv-cache
+      # Unit tests
+      - name: Run all tests
+        run: uv run poe all-tests
         working-directory: ./python
-      - name: Move coverage file - main
-        run: |
-          mv ./packages/${{ env.PACKAGE_NAME }}/coverage.xml coverage_${{ matrix.OS }}_${{ matrix.python-version }}_${{ env.PACKAGE_NAME }}.xml
-        working-directory: ./python
-      - name: Upload coverage artifact - main
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-${{ matrix.OS }}-${{ matrix.python-version }}-${{ env.PACKAGE_NAME }}
-          path: ./python/coverage_${{ matrix.OS }}_${{ matrix.python-version }}_${{ env.PACKAGE_NAME }}.xml
-      # Azure package tests
-      - name: Set environment variables - azure - win
-        if: ${{ matrix.os == 'windows-latest' }}
-        run: |
-          echo "PACKAGE_NAME=azure" | Out-File -FilePath $env:GITHUB_ENV -Append
-      - name: Set environment variables - azure
-        if: ${{ matrix.os != 'windows-latest' }}
-        run: |
-          echo "PACKAGE_NAME=azure" >> $GITHUB_ENV
-      - name: Test with pytest - azure
-        run: uv run poe --directory ./packages/${{ env.PACKAGE_NAME }} test --junitxml=coverage.xml
-        working-directory: ./python
-      - name: Move coverage file - azure
-        run: |
-          mv ./packages/${{ env.PACKAGE_NAME }}/coverage.xml coverage_${{ matrix.OS }}_${{ matrix.python-version }}_${{ env.PACKAGE_NAME }}.xml
-        working-directory: ./python
-      - name: Upload coverage artifact - azure
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-${{ matrix.OS }}-${{ matrix.python-version }}-${{ env.PACKAGE_NAME }}
-          path: ./python/coverage_${{ matrix.OS }}_${{ matrix.python-version }}_${{ env.PACKAGE_NAME }}.xml
-      # Foundry package tests
-      - name: Set environment variables - foundry - win
-        if: ${{ matrix.os == 'windows-latest' }}
-        run: |
-          echo "PACKAGE_NAME=foundry" | Out-File -FilePath $env:GITHUB_ENV -Append
-      - name: Set environment variables - foundry
-        if: ${{ matrix.os != 'windows-latest' }}
-        run: |
-          echo "PACKAGE_NAME=foundry" >> $GITHUB_ENV
-      - name: Test with pytest - foundry
-        run: uv run poe --directory ./packages/${{ env.PACKAGE_NAME }} test --junitxml=coverage.xml
-        working-directory: ./python
-      - name: Move coverage file - foundry
-        run: |
-          mv ./packages/${{ env.PACKAGE_NAME }}/coverage.xml coverage_${{ matrix.OS }}_${{ matrix.python-version }}_${{ env.PACKAGE_NAME }}.xml
-        working-directory: ./python
-      - name: Upload coverage artifact - foundry
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-${{ matrix.OS }}-${{ matrix.python-version }}-${{ env.PACKAGE_NAME }}
-          path: ./python/coverage_${{ matrix.OS }}_${{ matrix.python-version }}_${{ env.PACKAGE_NAME }}.xml
+
+      # Surface failing tests
       - name: Surface failing tests
         if: always()
         uses: pmeier/pytest-results-action@v0.7.2
@@ -108,5 +50,5 @@ jobs:
           path: ./python/**.xml
           summary: true
           display-options: fEX
-          fail-on-empty: true
+          fail-on-empty: false
           title: Test results

.gitignore

@@ -15,6 +15,7 @@ downloads/
 eggs/
 .eggs/
 lib/
+!python/packages/devui/frontend/src/lib/
 lib64/
 parts/
 sdist/
@@ -25,6 +26,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+TestResults/
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -69,7 +71,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/build/
 
 # PyBuilder
 .pybuilder/
@@ -173,9 +175,52 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 
+**/.DS_Store
 .DS_Store
 
 # Visual Studio 2015/2017 cache/options directory
 .vs/
 
 **/.user/**
+
+# Temporary files
+*.~tmp
+*.~bak
+*.~swp
+*.~swo
+
+# Temporary directories
+*tmp/
+*temp/
+*.tmp/
+*.temp/
+tmp*/
+temp*/
+.tmp/
+.temp/
+
+agents.md
+
+# AI
+.claude/
+WARP.md
+
+# Azurite storage emulator files
+*/__azurite_db_blob__.json
+*/__azurite_db_blob_extent__.json
+*/__azurite_db_queue__.json
+*/__azurite_db_queue_extent__.json
+*/__azurite_db_table__.json
+*/__blobstorage__/
+*/__queuestorage__/
+
+# Azure Functions local settings
+local.settings.json
+
+# Frontend
+**/frontend/node_modules/
+**/frontend/.vite/
+**/frontend/dist/
+
+# Database files
+*.db

COMMUNITY.md

@@ -0,0 +1,22 @@
+# Welcome to the Agent Framework Community
+
+Below are some ways that you can get involved in the Agent Framework Community.
+
+## Engage on GitHub
+
+- [Discussions](https://github.com/microsoft/agent-framework/discussions): Ask questions, provide feedback and ideas to what you'd like to see from the Agent Framework.
+- [Issues](https://github.com/microsoft/agent-framework/issues) - If you find a bug, unexpected behavior or have a feature request, please open an issue.
+- [Pull Requests](https://github.com/microsoft/agent-framework/pulls) - We welcome contributions! Please see our [Contributing Guide](https://github.com/microsoft/agent-framework/blob/main/CONTRIBUTING.md)
+
+We do our best to respond to each submission.
+
+## Public Community Office Hours
+
+We regularly have Community Office Hours that are open to the **public** to join.
+
+Add Agent Framework events to your calendar. We are running two community calls to accommodate different time zones for Q&A Office Hours:
+
+- **Americas & EMEA timezone:** Every Wednesday at 8:00 AM Pacific Time/17:00 CET. Adjusted for daylight savings. Join here: [AF-AG-SK-Americas-Europe-OfficeHours](https://aka.ms/sk-officehours).
+- **Asia Pacific timezone:** The second Wednesday of every month at 4:00 PM Pacific Time Wednesday. In much of Asia this occurs on Thursday local time. Adjusted for daylight savings. Join here: [AF-AG-SK-APAC-OfficeHours](https://aka.ms/sk-apac-officehours).
+
+If you are unable to make it live, all meetings will be recorded and posted online.

CONTRIBUTING.md

@@ -0,0 +1,119 @@
+# Contributing to Agent Framework
+
+You can contribute to Agent Framework with issues and pull requests (PRs). Simply
+filing issues for problems you encounter is a great way to contribute. Contributing
+code is greatly appreciated.
+
+## Reporting Issues
+
+We always welcome bug reports, API proposals and overall feedback. Here are a few
+tips on how you can make reporting your issue as effective as possible.
+
+### Where to Report
+
+New issues can be reported in our [list of issues](https://github.com/microsoft/agent-framework/issues).
+
+Before filing a new issue, please search the list of issues to make sure it does
+not already exist.
+
+If you do find an existing issue for what you wanted to report, please include
+your own feedback in the discussion. Do consider upvoting (👍 reaction) the original
+post, as this helps us prioritize popular issues in our backlog.
+
+### Writing a Good Bug Report
+
+Good bug reports make it easier for maintainers to verify and root cause the
+underlying problem.
+The better a bug report, the faster the problem will be resolved. Ideally, a bug
+report should contain the following information:
+
+- A high-level description of the problem.
+- A _minimal reproduction_, i.e. the smallest size of code/configuration required
+  to reproduce the wrong behavior.
+- A description of the _expected behavior_, contrasted with the _actual behavior_ observed.
+- Information on the environment: OS/distribution, CPU architecture, SDK version, etc.
+- Additional information, e.g. Is it a regression from previous versions? Are there
+  any known workarounds?
+
+## Contributing Changes
+
+Project maintainers will merge accepted code changes from contributors.
+
+### DOs and DON'Ts
+
+DO's:
+
+- **DO** follow the standard coding conventions
+
+  - [.NET](https://learn.microsoft.com/dotnet/csharp/fundamentals/coding-style/coding-conventions)
+  - [Python](https://pypi.org/project/black/)
+
+- **DO** give priority to the current style of the project or file you're changing
+  if it diverges from the general guidelines.
+- **DO** use the pre-commit hooks for python to ensure proper formatting.
+- **DO** include tests when adding new features. When fixing bugs, start with
+  adding a test that highlights how the current behavior is broken.
+- **DO** keep the discussions focused. When a new or related topic comes up
+  it's often better to create new issue than to side track the discussion.
+- **DO** clearly state on an issue that you are going to take on implementing it.
+- **DO** blog and tweet (or whatever) about your contributions, frequently!
+
+DON'Ts:
+
+- **DON'T** surprise us with big pull requests. Instead, file an issue and start
+  a discussion so we can agree on a direction before you invest a large amount of time.
+- **DON'T** commit code that you didn't write. If you find code that you think is a good
+  fit to add to Agent Framework, file an issue and start a discussion before proceeding.
+- **DON'T** submit PRs that alter licensing related files or headers. If you believe
+  there's a problem with them, file an issue and we'll be happy to discuss it.
+- **DON'T** make new APIs without filing an issue and discussing with us first.
+
+### Breaking Changes
+
+Contributions must maintain API signature and behavioral compatibility. Contributions
+that include breaking changes will be rejected. Please file an issue to discuss
+your idea or change if you believe that a breaking change is warranted.
+
+### Suggested Workflow
+
+We use and recommend the following workflow:
+
+1. Create an issue for your work.
+   - You can skip this step for trivial changes.
+   - Reuse an existing issue on the topic, if there is one.
+   - Get agreement from the team and the community that your proposed change is
+     a good one.
+   - Clearly state that you are going to take on implementing it, if that's the case.
+     You can request that the issue be assigned to you. Note: The issue filer and
+     the implementer don't have to be the same person.
+2. Create a personal fork of the repository on GitHub (if you don't already have one).
+3. In your fork, create a branch off of main (`git checkout -b mybranch`).
+   - Name the branch so that it clearly communicates your intentions, such as
+     "issue-123" or "githubhandle-issue".
+4. Make and commit your changes to your branch.
+5. Add new tests corresponding to your change, if applicable.
+6. Run the relevant scripts in [the section below](#development-scripts) to ensure that your build is clean and all tests are passing.
+7. Create a PR against the repository's **main** branch.
+   - State in the description what issue or improvement your change is addressing.
+   - Verify that all the Continuous Integration checks are passing.
+8. Wait for feedback or approval of your changes from the code maintainers.
+9. When area owners have signed off, and all checks are green, your PR will be merged.
+
+### Development scripts
+
+The scripts below are used to build, test, and lint within the project.
+
+- Python: see [python/DEV_SETUP.md](./python/DEV_SETUP.md).
+- .NET:
+  - Build: `dotnet build`
+  - Test: `dotnet test`
+  - Linting (auto-fix): `dotnet format`
+
+### PR - CI Process
+
+The continuous integration (CI) system will automatically perform the required
+builds and run tests (including the ones you are expected to run) for PRs. Builds
+and test runs must be clean.
+
+If the CI build fails for any reason, the PR issue will be updated with a link
+that can be used to determine the cause of the failure.

README.md

@@ -1,235 +1,179 @@
-# Get Started with Microsoft Agent Framework
+![Microsoft Agent Framework](docs/assets/readme-banner.png)
 
-Highlights
-- Flexible Agent Framework: build, orchestrate, and deploy AI agents and multi-agent systems
-- Multi-Agent Orchestration: Group chat, sequential, concurrent, and handoff patterns
-- Plugin Ecosystem: Extend with native functions, OpenAPI, Model Context Protocol (MCP), and more
-- LLM Support: OpenAI, Azure OpenAI, Azure AI Foundry, and more
-- Runtime Support: In-process and distributed agent execution
-- Multimodal: Text, vision, and function calling
-- Cross-Platform: .NET and Python implementations
+# Welcome to Microsoft Agent Framework!
 
-## Quick Install
+[![Microsoft Azure AI Foundry Discord](https://dcbadge.limes.pink/api/server/b5zjErwbQM?style=flat)](https://discord.gg/b5zjErwbQM)
+[![MS Learn Documentation](https://img.shields.io/badge/MS%20Learn-Documentation-blue)](https://learn.microsoft.com/en-us/agent-framework/)
+[![PyPI](https://img.shields.io/pypi/v/agent-framework)](https://pypi.org/project/agent-framework/)
+[![NuGet](https://img.shields.io/nuget/v/Microsoft.Agents.AI)](https://www.nuget.org/profiles/MicrosoftAgentFramework/)
+
+Welcome to Microsoft's comprehensive multi-language framework for building, orchestrating, and deploying AI agents with support for both .NET and Python implementations. This framework provides everything from simple chat agents to complex multi-agent workflows with graph-based orchestration.
+
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=AAgdMhftj8w" title="Watch the full Agent Framework introduction (30 min)">
+    <img src="https://img.youtube.com/vi/AAgdMhftj8w/hqdefault.jpg"
+         alt="Watch the full Agent Framework introduction (30 min)" width="480">
+  </a>
+</p>
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=AAgdMhftj8w">
+    Watch the full Agent Framework introduction (30 min)
+  </a>
+</p>
+
+## 📋 Getting Started
+
+### 📦 Installation
+
+Python
 
 ```bash
-pip install agent-framework
-# Optional: Add Azure integration
-pip install agent-framework[azure]
-# Optional: Add Foundry integration
-pip install agent-framework[foundry]
-# Optional: Both
-pip install agent-framework[azure,foundry]
+pip install agent-framework --pre
+# This will install all sub-packages, see `python/packages` for individual packages.
+# It may take a minute on first install on Windows.
 ```
 
-Supported Platforms:
-- Python: 3.10+
-- OS: Windows, macOS, Linux
-
-## 1. Setup API Keys
-
-Set as environment variables, or create a .env file at your project root:
+.NET
 
 ```bash
-OPENAI_API_KEY=sk-...
-OPENAI_CHAT_MODEL_ID=...
-...
-AZURE_OPENAI_API_KEY=...
-AZURE_OPENAI_ENDPOINT=...
-AZURE_OPENAI_CHAT_DEPLOYMENT_NAME=...
-...
-FOUNDRY_PROJECT_ENDPOINT=...
-FOUNDRY_MODEL_DEPLOYMENT_NAME=...
+dotnet add package Microsoft.Agents.AI
 ```
 
-You can also override environment variables by explicitly passing configuration parameters to the chat client constructor:
+### 📚 Documentation
 
-```python
-from agent_framework.azure import AzureChatClient
+- **[Overview](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview)** - High level overview of the framework
+- **[Quick Start](https://learn.microsoft.com/agent-framework/tutorials/quick-start)** - Get started with a simple agent
+- **[Tutorials](https://learn.microsoft.com/agent-framework/tutorials/overview)** - Step by step tutorials
+- **[User Guide](https://learn.microsoft.com/en-us/agent-framework/user-guide/overview)** - In-depth user guide for building agents and workflows
+- **[Migration from Semantic Kernel](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-semantic-kernel)** - Guide to migrate from Semantic Kernel
+- **[Migration from AutoGen](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-autogen)** - Guide to migrate from AutoGen
 
-chat_client = AzureChatClient(
-    api_key=...,
-    endpoint=...,
-    deployment_name=...,
-    api_version=...,
-)
-```
+### ✨ **Highlights**
 
-See the following [setup guide](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started) for more information.
+- **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/getting_started/workflows/) | [.NET workflows](./dotnet/samples/GettingStarted/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
+  - [DevUI package](./python/packages/devui/)
 
-## 2. Create a Simple Agent
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=mOAaGY4WPvc">
+    <img src="https://img.youtube.com/vi/mOAaGY4WPvc/hqdefault.jpg" alt="See the DevUI in action" width="480">
+  </a>
+</p>
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=mOAaGY4WPvc">
+    See the DevUI in action (1 min)
+  </a>
+</p>
 
-Create agents and invoke them directly:
+- **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/getting_started/observability/) | [.NET telemetry](./dotnet/samples/GettingStarted/AgentOpenTelemetry/)
+- **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
+  - [Python examples](./python/samples/getting_started/agents/) | [.NET examples](./dotnet/samples/GettingStarted/AgentProviders/)
+- **Middleware**: Flexible middleware system for request/response processing, exception handling, and custom pipelines
+  - [Python middleware](./python/samples/getting_started/middleware/) | [.NET middleware](./dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/)
+
+### 💬 **We want your feedback!**
+
+- For bugs, please file a [GitHub issue](https://github.com/microsoft/agent-framework/issues).
+
+## Quickstart
+
+### Basic Agent - Python
+
+Create a simple Azure Responses Agent that writes a haiku about the Microsoft Agent Framework
 
 ```python
+# pip install agent-framework --pre
+# Use `az login` to authenticate with Azure CLI
+import os
 import asyncio
-from agent_framework import ChatClientAgent
-from agent_framework.openai import OpenAIChatClient
+from agent_framework.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+
 
 async def main():
-    agent = ChatClientAgent(
-        chat_client=OpenAIChatClient(),
-        instructions="""
-        1) A robot may not injure a human being...
-        2) A robot must obey orders given it by human beings...
-        3) A robot must protect its own existence...
-
-        Give me the TLDR in exactly 5 words.
-        """
+    # Initialize a chat agent with Azure OpenAI Responses
+    # the endpoint, deployment name, and api version can be set via environment variables
+    # or they can be passed in directly to the AzureOpenAIResponsesClient constructor
+    agent = AzureOpenAIResponsesClient(
+        # endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
+        # deployment_name=os.environ["AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME"],
+        # api_version=os.environ["AZURE_OPENAI_API_VERSION"],
+        # api_key=os.environ["AZURE_OPENAI_API_KEY"],  # Optional if using AzureCliCredential
+        credential=AzureCliCredential(), # Optional, if using api_key
+    ).create_agent(
+        name="HaikuBot",
+        instructions="You are an upbeat assistant that writes beautifully.",
     )
 
-    result = await agent.run("Summarize the Three Laws of Robotics")
-    print(result)
-
-asyncio.run(main())
-# Output: Protect humans, obey, self-preserve, prioritized.
-```
-
-## 3. Directly Use Chat Clients (No Agent Required)
-
-You can use the chat client classes directly for advanced workflows:
-
-```python
-import asyncio
-from agent_framework.openai import OpenAIChatClient
-from agent_framework import ChatMessage, ChatRole
-
-async def main():
-    client = OpenAIChatClient()
-
-    messages = [
-        ChatMessage(role=ChatRole.SYSTEM, text="You are a helpful assistant."),
-        ChatMessage(role=ChatRole.USER, text="Write a haiku about Agent Framework.")
-    ]
-
-    response = await client.get_response(messages)
-    print(response.messages[0].text)
-
-    """
-    Output:
-
-    Agents work in sync,
-    Framework threads through each task—
-    Code sparks collaboration.
-    """
-
-asyncio.run(main())
-```
-
-## 4. Build an Agent with Tools and Functions
-
-Enhance your agent with custom tools and function calling:
-
-```python
-import asyncio
-from typing import Annotated
-from random import randint
-from pydantic import Field
-from agent_framework import ChatClientAgent
-from agent_framework.openai import OpenAIChatClient
-
-
-def get_weather(
-    location: Annotated[str, Field(description="The location to get the weather for.")],
-) -> str:
-    """Get the weather for a given location."""
-    conditions = ["sunny", "cloudy", "rainy", "stormy"]
-    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
-
-
-def get_menu_specials() -> str:
-    """Get today's menu specials."""
-    return """
-    Special Soup: Clam Chowder
-    Special Salad: Cobb Salad
-    Special Drink: Chai Tea
-    """
-
-
-async def main():
-    agent = ChatClientAgent(
-        chat_client=OpenAIChatClient(),
-        instructions="You are a helpful assistant that can provide weather and restaurant information.",
-        tools=[get_weather, get_menu_specials]
-    )
-
-    response = await agent.run("What's the weather in Amsterdam and what are today's specials?")
-    print(response)
-
-    """
-    Output:
-    The weather in Amsterdam is sunny with a high of 22°C. Today's specials include
-    Clam Chowder soup, Cobb Salad, and Chai Tea as the special drink.
-    """
+    print(await agent.run("Write a haiku about Microsoft Agent Framework."))
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-You can explore additional agent samples [here](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents).
+### Basic Agent - .NET
 
-## 5. Multi-Agent Orchestration
+Create a simple Agent, using OpenAI Responses, that writes a haiku about the Microsoft Agent Framework
 
-Coordinate multiple agents to collaborate on complex tasks using orchestration patterns:
+```c#
+// dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
+using System;
+using OpenAI;
 
-```python
-import asyncio
-from agent_framework import ChatClientAgent
-from agent_framework.openai import OpenAIChatClient
+// Replace the <apikey> with your OpenAI API key.
+var agent = new OpenAIClient("<apikey>")
+    .GetOpenAIResponseClient("gpt-4o-mini")
+    .CreateAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
-
-async def main():
-    # Create specialized agents
-    writer = ChatClientAgent(
-        chat_client=OpenAIChatClient(),
-        name="Writer",
-        instructions="You are a creative content writer. Generate and refine slogans based on feedback."
-    )
-
-    reviewer = ChatClientAgent(
-        chat_client=OpenAIChatClient(),
-        name="Reviewer",
-        instructions="You are a critical reviewer. Provide detailed feedback on proposed slogans."
-    )
-
-    # Sequential workflow: Writer creates, Reviewer provides feedback
-    task = "Create a slogan for a new electric SUV that is affordable and fun to drive."
-
-    # Step 1: Writer creates initial slogan
-    initial_result = await writer.run(task)
-    print(f"Writer: {initial_result}")
-
-    # Step 2: Reviewer provides feedback
-    feedback_request = f"Please review this slogan: {initial_result}"
-    feedback = await reviewer.run(feedback_request)
-    print(f"Reviewer: {feedback}")
-
-    # Step 3: Writer refines based on feedback
-    refinement_request = f"Please refine this slogan based on the feedback: {initial_result}\nFeedback: {feedback}"
-    final_result = await writer.run(refinement_request)
-    print(f"Final Slogan: {final_result}")
-
-    # Example Output:
-    # Writer: "Charge Forward: Affordable Adventure Awaits!"
-    # Reviewer: "Good energy, but 'Charge Forward' is overused in EV marketing..."
-    # Final Slogan: "Power Up Your Adventure: Premium Feel, Smart Price!"
-
-if __name__ == "__main__":
-    asyncio.run(main())
+Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```
 
-**Note**: Advanced orchestration patterns like GroupChat, Sequential, and Concurrent orchestrations are coming soon.
+Create a simple Agent, using Azure OpenAI Responses with token based auth, that writes a haiku about the Microsoft Agent Framework
+
+```c#
+// dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
+// dotnet add package Azure.Identity
+// Use `az login` to authenticate with Azure CLI
+using System;
+using OpenAI;
+
+// Replace <resource> and gpt-4o-mini with your Azure OpenAI resource name and deployment name.
+var agent = new OpenAIClient(
+    new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"),
+    new OpenAIClientOptions() { Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1") })
+    .GetOpenAIResponseClient("gpt-4o-mini")
+    .CreateAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+
+Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
+```
 
 ## More Examples & Samples
 
-- [Getting Started with Agents](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/agents): Basic agent creation and tool usage
-- [Chat Client Examples](https://github.com/microsoft/agent-framework/tree/main/python/samples/getting_started/chat_client): Direct chat client usage patterns
-- [Azure Integration](https://github.com/microsoft/agent-framework/tree/main/python/packages/azure): Azure OpenAI and AI Foundry integration
-- [.NET Orchestration Samples](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/Orchestration): Advanced multi-agent patterns (.NET)
+### Python
 
-## Agent Framework Documentation
+- [Getting Started with Agents](./python/samples/getting_started/agents): basic agent creation and tool usage
+- [Chat Client Examples](./python/samples/getting_started/chat_client): direct chat client usage patterns
+- [Getting Started with Workflows](./python/samples/getting_started/workflows): basic workflow creation and integration with agents
 
-- [Agent Framework Repository](https://github.com/microsoft/agent-framework)
-- [Python Package Documentation](https://github.com/microsoft/agent-framework/tree/main/python)
-- [.NET Package Documentation](https://github.com/microsoft/agent-framework/tree/main/dotnet)
-- [Design Documents](https://github.com/microsoft/agent-framework/tree/main/docs/design)
-- Learn docs are coming soon.
+### .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
+
+## Contributor Resources
+
+- [Contributing Guide](./CONTRIBUTING.md)
+- [Python Development Guide](./python/DEV_SETUP.md)
+- [Design Documents](./docs/design)
+- [Architectural Decision Records](./docs/decisions)
+
+## Important Notes
+
+If you use the Microsoft Agent Framework to build applications that operate with third-party servers or agents, you do so at your own risk. We recommend reviewing all data being shared with third-party servers or agents and being cognizant of third-party practices for retention and location of data. It is your responsibility to manage whether your data will flow outside of your organization's Azure compliance and geographic boundaries and any related implications.

SUPPORT.md

@@ -1,13 +1,3 @@
-# TODO: The maintainer of this repo has not yet edited this file
-
-**REPO OWNER**: Do you want Customer Service & Support (CSS) support for this product/project?
-
-- **No CSS support:** Fill out this template with information about how to file issues and get help.
-- **Yes CSS support:** Fill out an intake form at [aka.ms/onboardsupport](https://aka.ms/onboardsupport). CSS will work with/help you to determine next steps.
-- **Not sure?** Fill out an intake as though the answer were "Yes". CSS will help you decide.
-
-*Then remove this first heading from this SUPPORT.MD file before publishing your repo.*
-
 # Support
 
 ## How to file issues and get help  
@@ -16,9 +6,11 @@ This project uses GitHub Issues to track bugs and feature requests. Please searc
 issues before filing new issues to avoid duplicates.  For new issues, file your bug or 
 feature request as a new Issue.
 
-For help and questions about using this project, please **REPO MAINTAINER: INSERT INSTRUCTIONS HERE 
-FOR HOW TO ENGAGE REPO OWNERS OR COMMUNITY FOR HELP. COULD BE A STACK OVERFLOW TAG OR OTHER
-CHANNEL. WHERE WILL YOU HELP PEOPLE?**.
+For help and questions about using this project, please create a GitHub issue.
+
+AI Support team will support Microsoft Agent Framework issues for customers under a **Unified support agreement when the issue arises from usage of Azure AI services** (Foundry Models, Foundry Agents etc.) in conjunction with the SDK. Conversely, if customer has any other / non unified support agreement and/or Agent Framework SDK is used in a way **not involving an Azure service**, it is treated as a purely open-source tool – Microsoft’s support organization will not handle it, and users should use GitHub or forums for assistance
+
+For Copilot Studio SDK implementation issues, customers should use GitHub Issues for assistance, as outlined above. Conversely, for prerequisites managed within the Copilot Studio portal, customers can rely on the standard Microsoft Copilot Studio support channels.
 
 ## Microsoft Support Policy  
 

TRANSPARENCY_FAQ.md

@@ -0,0 +1,141 @@
+# Responsible AI Transparency FAQs
+
+**What is Microsoft Agent Framework?**
+
+Microsoft Agent Framework is a comprehensive multi-language (C#/.NET and Python) framework for building, orchestrating, and deploying AI agents and multi-agent workflows. The system takes user instructions and conversation inputs and produces intelligent responses through AI agents that can integrate with various LLM providers (OpenAI, Azure OpenAI, Azure AI Foundry). It provides both simple chat agents and complex multi-agent workflows with graph-based orchestration.
+
+**What can Microsoft Agent Framework do?**
+
+The framework offers: 
+
+- **Agent Creation**: Build AI agents with custom instructions and tools
+- **Multi-Agent Orchestration**: Group chat, sequential, concurrent, and handoff patterns
+- **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, time-travel, and Human-in-the-loop
+- **Extensibility Framework**: Extend with native functions, A2A, Model Context Protocol (MCP)
+- **LLM Integration**: Support for OpenAI, Azure OpenAI, Azure AI Foundry, and other providers
+- **Runtime Support**: Both in-process and distributed agent execution
+
+**What is/are Microsoft Agent Framework's intended use(s)?**
+
+Intended uses include: 
+
+- **Enterprise AI Applications**: Building AI-powered business applications with multiple specialized agents
+- **Multi-Agent Collaboration**: Coordinating multiple AI agents for complex tasks (e.g., content creation with writer/reviewer agents)
+- **Workflow Automation**: Orchestrating AI agents and deterministic functions in business processes
+
+**How was Microsoft Agent Framework evaluated? What metrics are used to measure performance?**
+
+Microsoft Agent Framework is a development framework rather than a deployed AI system. The framework undergoes engineering testing for component functionality, integration testing for multi-agent scenarios, and conformance testing across .NET and Python implementations. However, AI performance metrics such as accuracy, helpfulness, and safety are dependent on the underlying LLM providers and specific application implementations. Developers using the framework should conduct application-specific evaluation including performance, safety, and accuracy testing appropriate to their chosen LLM providers, deployment contexts, and use cases.
+
+**What are the limitations of Microsoft Agent Framework? How can users minimize the impact of Microsoft Agent Framework's limitations when using the system?**
+
+Microsoft Agent Framework relies on existing LLMs. Using the framework retains common limitations of large language models, including:
+
+**LLM-Inherited Limitations**:
+
+- **Data Biases**: Large language models, trained on extensive data, can inadvertently carry biases present in the source data. Consequently, the models may generate outputs that could be potentially biased or unfair.
+- **Lack of Contextual Understanding**: Despite their impressive capabilities in language understanding and generation, these models exhibit limited real-world understanding, resulting in potential inaccuracies or nonsensical responses.
+- **Lack of Transparency**: Due to the complexity and size, large language models can act as 'black boxes,' making it difficult to comprehend the rationale behind specific outputs or decisions.
+- **Content Harms**: There are various types of content harms that large language models can cause. It is important to be aware of them when using these models, and to take actions to prevent them. It is recommended to leverage various content moderation services provided by different companies and institutions.
+- **Inaccurate or ungrounded content**: It is important to be aware and cautious not to entirely rely on a given language model for critical decisions or information that might have deep impact as it is not obvious how to prevent these models to fabricate content without high authority input sources.
+- **Potential for Misuse**: Without suitable safeguards, there is a risk that these models could be maliciously used for generating disinformation or harmful content.
+
+**Framework-Specific Limitations**:
+
+- **Platform Requirements**: Python 3.10+ required, specific .NET versions (.NET 8.0, 9.0, netstandard2.0, net472)
+- **API Dependencies**: Requires proper configuration of LLM provider keys and endpoints
+- **Orchestration Features**: Advanced orchestration patterns like GroupChat, Sequential, and Concurrent orchestrations are "coming soon" for Python implementation
+- **Privacy and Data Protection**: The framework allows for human participation in conversations between agents. It is important to ensure that user data and conversations are protected and that developers use appropriate measures to safeguard privacy.
+- **Accountability and Transparency**: The framework involves multiple agents conversing and collaborating, it is important to establish clear accountability and transparency mechanisms. Users should be able to understand and trace the decision-making process of the agents involved in order to ensure accountability and address any potential issues or biases.
+- **Security & unintended consequences**: The use of multi-agent conversations and automation in complex tasks may have unintended consequences. Especially, allowing agents to make changes in external environments through tool calls or function execution could pose significant risks. Developers should carefully consider the potential risks and ensure that appropriate safeguards are in place to prevent harm or negative outcomes, including keeping a human in the loop for decision making.
+
+**Mitigation Steps**:
+
+- Follow setup guides for proper API key configuration
+- Use provided samples as starting points to avoid configuration issues
+- Monitor the GitHub repository for feature releases and updates
+- Implement content moderation and safety measures when deploying agents
+- Maintain human oversight for critical decisions and actions
+- Use appropriate security measures to protect user data and conversations
+
+**What operational factors and settings allow for effective and responsible use of Microsoft Agent Framework?**
+
+**Configuration Requirements**:
+
+- **API Keys**: Proper configuration of your LLM provider credentials and endpoints 
+
+- **Model Selection**: Choose appropriate deployment models for specific use cases 
+
+- **Tool Integration**: Careful selection and validation of external tools and MCP servers 
+
+- **Type Safety**: Strong typing and compatibility validation between agents and threads 
+
+ 
+
+**Responsible Development Practices**: 
+
+- **Human Oversight**: Microsoft Agent Framework prioritizes human involvement in multi-agent conversations. Users should maintain oversight and can step in to provide feedback to agents and steer them in the correct direction. In critical applications, users should confirm actions before they are executed. 
+
+- **Agent Modularity**: Modularity allows agents to have different levels of information access. Additional agents can assume roles that help keep other agents in check. For example, one can easily add a dedicated agent to play the role of safeguard. 
+
+- **LLM Selection**: Users can choose the LLM that is optimized for responsible use. We encourage developers to review and follow LLM providers’ policies. Developers should add content moderation and/or use safety metaprompts when using agents, like they would do when using LLMs directly. 
+
+- **Security Measures**: Implement appropriate security measures for tool execution and external system integrations. Consider using containerization or sandboxing for code execution scenarios to prevent unintended system changes. 
+
+- **Testing and Validation**: Use provided testing frameworks (unit, integration, conformance tests) to validate agent behavior and ensure reliability. 
+
+- **Monitoring and Observability**: Implement proper error handling, logging, and use OpenTelemetry for observability to track agent behavior and identify potential issues. 
+
+ 
+
+**How do I provide feedback on Microsoft Agent Framework?**
+
+- **Bug Reports**: File issues at https://github.com/microsoft/agent-framework/issues
+
+**What are external services and how does Microsoft Agent Framework use them?**
+
+The framework supports multiple external service types: 
+
+- **Native Functions**: Custom Python/C# functions that agents can invoke
+- **A2A (Agent2Agent)Integration**: Agent-to-agent communication and coordination
+- **Model Context Protocol (MCP)**: External tools and data sources through MCP servers
+- **Tools & External Capabilities**: Agent-invokable external services
+
+External service development is open to developers who can create custom functions and integrate external APIs. Users have control over which tools are provided to agents during agent creation.
+
+**What data can Microsoft Agent Framework provide to external services? What permissions do Microsoft Agent Framework external services have?**
+
+Microsoft Agent Framework is an open-source framework that allows integration with various types of external services. The data access and permissions depend on how you configure and implement these integrations:
+
+**Data Access by Service Type**:
+
+- **Native Functions**: Custom functions you develop have access to whatever data you explicitly pass to them as parameters
+- **A2A (Agent2Agent)**: External agents can access conversation history, messages, and any data you configure to share through the communication interface
+- **Model Context Protocol (MCP) Servers**: External MCP servers can access data according to the specific MCP server implementation and your configuration
+- **External Tools**: Third-party tools and APIs have access to data you explicitly send to them through function calls
+
+**Important Security Considerations**:
+
+- **Community and Third-Party Services**: Microsoft Agent Framework is an open-source project. When using community-developed tools or services from third-party providers, it is your responsibility to evaluate and ensure their safety, security, and compliance with your data protection requirements.
+- **Data Boundary Considerations**: When connecting Azure-hosted agents to external agents or services, data may leave the Azure boundary and Microsoft's security perimeter. You should verify the data handling practices, security measures, and compliance certifications of external providers before sharing sensitive or regulated data.
+- **Provider Due Diligence**: Before integrating any external service, you should review their privacy policies, security practices, data retention policies, and terms of service to ensure they meet your organization's requirements and regulatory obligations.
+- **Data Minimization**: Only provide external services with the minimum data necessary for their function. Avoid sharing sensitive, personal, or confidential information unless absolutely required and properly secured.
+
+**Recommendation**: Consult with your organization's security, privacy, and legal teams before integrating external services, especially in production environments handling sensitive data.
+
+**What kinds of issues may arise when using Microsoft Agent Framework enabled with external services?**
+
+**Potential Issues**:
+
+- **API Key Security**: Risk of exposing API keys in configuration or logs
+- **Tool Reliability**: External tool failures or unavailability affecting agent performance
+- **Type Safety**: Mismatched message types between agents and handlers
+- **Provider Dependencies**: Reliance on external LLM provider availability and rate limits
+
+**Mitigation Mechanisms**:
+
+- Follow security best practices for API key management
+- Implement proper error handling for tool failures
+- Use strong typing and compatibility validation
+- Monitor external service health and implement fallback strategies
+- Regular repository updates during preview period for bug fixes 

docs/FAQS.md

@@ -0,0 +1,54 @@
+# Frequently Asked Questions
+
+### How do I get access to nightly builds?
+
+Nightly builds of the Agent Framework are available [here](https://github.com/orgs/microsoft/packages?repo_name=agent-framework).
+
+To download nightly builds follow the following steps:
+
+1. You will need a GitHub account to complete these steps.
+1. Create a GitHub Personal Access Token with the `read:packages` scope using these [instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic).
+1. If your account is part of the Microsoft organization then you must authorize the `Microsoft` organization as a single sign-on organization.
+    1. Click the "Configure SSO" next to the Personal Access Token you just created and then authorize `Microsoft`.
+1. Use the following command to add the Microsoft GitHub Packages source to your NuGet configuration:
+
+    ```powershell
+    dotnet nuget add source --username GITHUBUSERNAME --password GITHUBPERSONALACCESSTOKEN --store-password-in-clear-text --name GitHubMicrosoft "https://nuget.pkg.github.com/microsoft/index.json"
+    ```
+
+1. Or you can manually create a `NuGet.Config` file.
+
+    ```xml
+    <?xml version="1.0" encoding="utf-8"?>
+    <configuration>
+      <packageSources>
+        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
+        <add key="GitHubMicrosoft" value="https://nuget.pkg.github.com/microsoft/index.json" />
+      </packageSources>
+    
+      <packageSourceMapping>
+        <packageSource key="nuget.org">
+          <package pattern="*" />
+        </packageSource>
+        <packageSource key="GitHubMicrosoft">
+          <package pattern="*nightly"/>
+        </packageSource>
+      </packageSourceMapping>
+    
+      <packageSourceCredentials>
+        <GitHubMicrosoft>
+          <add key="Username" value="<Your GitHub Id>" />
+          <add key="ClearTextPassword" value="<Your Personal Access Token>" />
+        </GitHubMicrosoft>
+      </packageSourceCredentials>
+    </configuration>
+    ```
+
+    * If you place this file in your project folder make sure to have Git (or whatever source control you use) ignore it.
+    * For more information on where to store this file go [here](https://learn.microsoft.com/en-us/nuget/reference/nuget-config-file).
+1. You can now add packages from the nightly build to your project.
+    * E.g. use this command `dotnet add package Microsoft.Agents.AI --version 0.0.1-nightly-250731.6-alpha`
+1. And the latest package release can be referenced in the project like this:
+    * `<PackageReference Include="Microsoft.Agents.AI" Version="*-*" />`
+
+For more information see: <https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry>

docs/decisions/0001-agent-run-response.md

@@ -499,7 +499,7 @@ We need to decide what AIContent types, each agent response type will be mapped
 | AWS (Strands) | **Approach 2** Supports a special invocation method called [structured_output](https://strandsagents.com/latest/api-reference/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 |
-| A2A | **Informal Approach 2** Doesn't formally support schema negotiation, but [hints can be provided via metadata](https://a2aproject.github.io/A2A/v0.2.5/specification/#97-structured-data-exchange-requesting-and-providing-json) at invocation 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 |
 
 ### Response Reason Support
@@ -511,5 +511,5 @@ We need to decide what AIContent types, each agent response type will be mapped
 | AWS (Strands) | Exposes a [stop_reason](https://strandsagents.com/latest/api-reference/types/#strands.types.event_loop.StopReason) property on the [AgentResult](https://strandsagents.com/latest/api-reference/agent/#strands.agent.agent_result.AgentResult) class with options that are tied closely to LLM operations. |
 | LangGraph | No equivalent present, output contains only [messages](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) |
 | Agno | [No equivalent present](https://docs.agno.com/reference/agents/run-response) |
-| A2A | No equivalent present, response only contains a [message](https://a2aproject.github.io/A2A/v0.2.5/specification/#64-message-object) or [task](https://a2aproject.github.io/A2A/v0.2.5/specification/#61-task-object). |
+| A2A | No equivalent present, response only contains a [message](https://a2a-protocol.org/latest/specification/#64-message-object) or [task](https://a2a-protocol.org/latest/specification/#61-task-object). |
 | Protocol Activity | [No equivalent present.](https://github.com/microsoft/Agents/blob/main/specs/activity/protocol-activity.md) |

docs/decisions/0003-agent-opentelemetry-instrumentation.md

@@ -139,14 +139,6 @@ using var telemetryAgent = baseAgent.WithOpenTelemetry();
 var response = await telemetryAgent.RunAsync(messages);
 ```
 
-### Integration with AppContext Switch
-
-The implementation integrates with the standard .NET telemetry enablement pattern:
-
-```csharp
-AppContext.SetSwitch("Microsoft.Extensions.AI.Agents.EnableTelemetry", true);
-```
-
 ### Relationship to Microsoft.Extensions.AI
 
 This implementation follows the exact patterns established by Microsoft.Extensions.AI's OpenTelemetry instrumentation, ensuring consistency across the AI ecosystem and leveraging proven patterns for telemetry integration.

docs/decisions/0004-foundry-sdk-extensions.md

@@ -0,0 +1,62 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: proposed
+contact: markwallace-microsoft
+date: 2025-08-06
+deciders: markwallace-microsoft, westey-m, quibitron, trrwilson
+consulted: 
+informed: 
+---
+
+# `Azure.AI.Agents.Persistent` package Extensions Methods for Agent Framework
+
+## Context and Problem Statement
+
+To align the `Azure.AI.Agents.Persistent` package and Agent Framework a set of extensions methods have been created which allow a developer to create or retrieve an `AIAgent` using the `PersistentAgentsClient`.
+The purpose of this ADR is to decide where these extension methods should live.
+
+## Decision Drivers
+
+- Provide the optimum experience for developers.
+- Avoid adding additional dependencies to the `Azure.AI.Agents.Persistent` package (and not in the future)
+
+## Considered Options
+
+- Add the extension methods to the `Azure.AI.Agents.Persistent` package and change it's dependencies
+- Add the extension methods to the `Azure.AI.Agents.Persistent` package without changing it's dependencies
+- Add the extension methods to a `Microsoft.Extensions.AI.Azure` package
+
+
+### Add the extension methods to the `Azure.AI.Agents.Persistent` package and change it's dependencies
+
+- `Azure.AI.Agents.Persistent` would depend on `Microsoft.Extensions.AI` instead of `Microsoft.Extensions.AI.Abstractions`
+
+- Good because, extension methods are in the `Azure.AI.Agents.Persistent` package and can be easily kept up-to-date
+- Good because, developers don't need to explicitly depend on a new package to get Agent Framework functionality
+- Bad because, it introduces additional dependencies which would possibly grow overtime
+
+
+### - Add the extension methods to the `Azure.AI.Agents.Persistent` package without changing it's dependencies
+
+- `Azure.AI.Agents.Persistent` would depend on `Microsoft.Extensions.AI.Abstractions` (as it currently does)
+- `ChatClientAgent` and `FunctionInvokingChatClient` would move to `Microsoft.Extensions.AI.Abstractions`
+
+- Good because, extension methods are in the `Azure.AI.Agents.Persistent` package and can be easily kept up-to-date
+- Good because, developers don't need to explicitly depend on a new package to get Agent Framework functionality
+- Good because, it introduces minimal additional dependencies
+- Bad because, it adds additional dependencies to `Microsoft.Extensions.AI.Abstractions` and these additional dependencies add up as transitive to `Azure`.AI.Agents.Persistent`
+
+
+### Add the extension methods to a `Microsoft.Extensions.AI.Azure` package
+
+- Introduce a new package called `Microsoft.Extensions.AI.Azure` where the extension methods would live
+- `Azure.AI.Agents.Persistent` does not change
+
+- Good because, it introduces no additional dependencies to `Azure.AI.Agents.Persistent` package
+- Bad because, extension methods are not in the `Azure.AI.Agents.Persistent` package and cannot be easily kept up-to-date
+- Bad because, developers need to explicitly depend on a new package to get Agent Framework functionality
+
+## Decision Outcome
+
+Chosen option: "Add the extension methods to a `Microsoft.Extensions.AI.Azure` package", because
+it introduces no additional dependencies to `Azure.AI.Agents.Persistent` package.

docs/decisions/0005-python-naming-conventions.md

@@ -0,0 +1,70 @@
+---
+status: accepted
+contact: eavanvalkenburg
+date: 2025-09-04
+deciders: markwallace-microsoft, dmytrostruk, peterychang, ekzhu, sphenry
+consulted: taochenosu, alliscode, moonbox3, johanste
+---
+
+# Python naming conventions and renames (ADR)
+
+## Context and Problem Statement
+
+The project has a public .NET surface and a Python surface. During a cross-language alignment effort the community proposed renames to make the Python surface more idiomatic while preserving discoverability and mapping to the .NET names. This ADR captures the final naming decisions (or the proposed ones), the rationale, and the alternatives considered and rejected.
+
+## Decision drivers
+
+- Follow Python naming conventions (PEP 8) where appropriate (snake_case for functions and module-level variables, PascalCase for classes).
+- Preserve conceptual parity with .NET names to make it easy for developers reading both surfaces to correlate types and behaviors.
+- Avoid ambiguous or overloaded names in Python that could conflict with stdlib, common third-party packages, or existing package/module names.
+- Prefer clarity and discoverability in the public API surface over strict symmetry with .NET when Python conventions conflict.
+- Minimize churn and migration burden for existing Python users where backwards compatibility is feasible.
+
+## Principles applied
+
+- Map .NET PascalCase class names to PascalCase Python classes when they represent types.
+- Map .NET method/field names that are camelCase to snake_case in Python where they will be used as functions or module-level attributes.
+- When a .NET name is an acronym or initialism, use Python-friendly casing (e.g., `Http` -> `HTTP` in classes, but acronyms in function names should be lowercased per PEP 8 where sensible).
+- Avoid names that shadow common stdlib modules (e.g., `logging`, `asyncio`) or widely used third-party modules.
+- When multiple reasonable Python names exist, prefer the one that communicates intent most clearly to Python users, and record rejected alternatives in the table with justification.
+
+## Renaming table
+
+The table below represents the majority of the naming changes discussed in issue #506. Each row has:
+- Original and/or .NET name — the canonical name used in dotnet or earlier Python variants.
+- New name — the chosen Python name.
+- Status — accepted if the new name differs from the original, rejected if unchanged.
+- Reasoning — short rationale why the new name was chosen.
+- Rejected alternatives — other candidate new names that were considered and rejected; include the rejected 'new name' values and the reason each was rejected.
+
+| Original and/or .NET name | New name (Python) | Status | Reasoning | Rejected alternatives (as "new name" + reason rejected) |
+|---|---|---|---|---|
+| AIAgent | AgentProtocol | accepted | The AI prefix is meaningless in the context of the Agent Framework, and the `protocol` suffix makes it very clear that this is a protocol, and not a concrete agent implementation. | <ul><li>AgentLike, not seen in many other places, but was a frontrunner.</li><li>Agent, as too generic.</li><li>BaseAgent/AbstractAgent, it is not a base/ABC class and should not be treated as such.</li></ul> |
+| ChatClientAgent | ChatAgent | accepted | Type name is shorter, while it is still clear that a ChatClient is used, also by virtue of the first parameter for initialization. | Agent, as too generic. |
+| ChatClient/IChatClient (in dotnet) | ChatClientProtocol | accepted | Keeping this protocol in sync with the AgentProtocol naming. | Similar as AgentProtocol. |
+| ChatClientBase | BaseChatClient | accepted | Following convention, serves as base class so, should be named accordingly. | None |
+| AITool | ToolProtocol | accepted | In line with other protocols. | Tool, too generic. |
+| AIToolBase | BaseTool | accepted | More descriptive than just Tool, while still concise. | AbstractTool/BaseTool, it is not an abstract/base class and should not be treated as such. |
+| ChatRole | Role | accepted | More concise while still clear in context. | None |
+| ChatFinishReason | FinishReason | accepted | More concise while still clear in context. | None |
+| AIContent | BaseContent | accepted | More accurate as it serves as the base class for all content types. | Content, too generic. |
+| AIContents | Contents | accepted | This is the annotated typing object that is the union of all concrete content types, so plural makes sense and since this is used as a type hint, the generic nature of the name is acceptable. | None |
+| AIAnnotations | Annotations | accepted | In sync with contents | None |
+| AIAnnotation | BaseAnnotation | accepted | In sync with contents | None |
+| *Mcp* & *Http* | *MCP* & *HTTP* | accepted | Acronyms should be uppercased in class names, according to PEP 8. | None |
+| `agent.run_streaming` | `agent.run_stream` | accepted | Shorter and more closely aligns with AutoGen and Semantic Kernel names for the same methods. | None |
+| `workflow.run_streaming` | `workflow.run_stream` | accepted | In sync with `agent.run_stream` and shorter and more closely aligns with AutoGen and Semantic Kernel names for the same methods. | None |
+| AgentRunResponse & AgentRunResponseUpdate | AgentResponse & AgentResponseUpdate | rejected | Rejected, because it is the response to a run invocation and AgentResponse is too generic. | None |
+| *Content | * | rejected | Rejected other content type renames (removing `Content` suffix) because it would reduce clarity and discoverability. | Item was also considered, but rejected as it is very similar to Content, but would be inconsistent with dotnet. |
+| ChatResponse & ChatResponseUpdate | Response & ResponseUpdate | rejected | Rejected, because Response is too generic. | None |
+
+## Naming guidance
+In general Python tends to prefer shorter names, while .NET tends to prefer more descriptive names. The table above captures the specific renames agreed upon, but in general the following guidelines were applied:
+- Use [PEP 8](https://peps.python.org/pep-0008/) for generic naming conventions (snake_case for functions and module-level variables, PascalCase for classes).
+
+When mapping .NET names to Python:
+- Remove `AI` prefix when appropriate, as it is often redundant in the context of an AI SDK.
+- Remove `Chat` prefix when the context is clear (e.g., Role and FinishReason).
+- Use `Protocol` suffix for interfaces/protocols to clarify their purpose.
+- Use `Base` prefix for base classes that are not abstract but serve as a common ancestor for internal implementations.
+- When readability improves while it is still easy to understand what it does and how it maps to the .NET name, prefer the shorter name.

docs/decisions/0006-userapproval.md

@@ -0,0 +1,521 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+contact: westey-m
+date: 2025-09-12 {YYYY-MM-DD when the decision was last updated}
+deciders: sergeymenshykh, markwallace-microsoft, rogerbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub, peterychang
+consulted: 
+informed: 
+---
+
+# Agent User Approvals Content Types and FunctionCall approvals Design
+
+## Context and Problem Statement
+
+When agents are operating on behalf of a user, there may be cases where the agent requires user approval to continue an operation.
+This is complicated by the fact that an agent may be remote and the user may not immediately be available to provide the approval.
+
+Inference services are also increasingly supporting built-in tools or service side MCP invocation, which may require user approval before the tool can be invoked.
+
+This document aims to provide options and capture the decision on how to model this user approval interaction with the agent caller.
+
+See various features that would need to be supported via this type of mechanism, plus how various other frameworks support this:
+
+- Also see [dotnet issue 6492](https://github.com/dotnet/extensions/issues/6492), which discusses the need for a similar pattern in the context of MCP approvals.
+- Also see [the openai human-in-the-loop guide](https://openai.github.io/openai-agents-js/guides/human-in-the-loop/#approval-requests).
+- Also see [the openai MCP guide](https://openai.github.io/openai-agents-js/guides/mcp/#optional-approval-flow).
+- Also see [MCP Approval Requests from OpenAI](https://platform.openai.com/docs/guides/tools-remote-mcp#approvals).
+- Also see [Azure AI Foundry MCP Approvals](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/model-context-protocol-samples?pivots=rest#submit-your-approval).
+- Also see [MCP Elicitation requests](https://modelcontextprotocol.io/specification/draft/client/elicitation)
+
+## Decision Drivers
+
+- Agents should encapsulate their internal logic and not leak it to the caller.
+- We need to support approvals for local actions as well as remote actions.
+- We need to support approvals for service-side tool use, such as remote MCP tool invocations
+- We should consider how other user input requests will be modeled, so that we can have a consistent approach for user input requests and approvals.
+
+## Considered Options
+
+### 1. Return a FunctionCallContent to the agent caller, that it executes
+
+This introduces a manual function calling element to agents, where the caller of the agent is expected to invoke the function if the user approves it.
+
+This approach is problematic for a number of reasons:
+
+- This may not work for remote agents (e.g. via A2A), where the function that the agent wants to call does not reside on the caller's machine.
+- The main value prop of an agent is to encapsulate the internal logic of the agent, but this leaks that logic to the caller, requiring the caller to know how to invoke the agent's function calls.
+- Inference services are introducing their own approval content types for server side tool or function invocation, and will not be addressed by this approach.
+
+### 2. Introduce an ApprovalCallback in AgentRunOptions and ChatOptions
+
+This approach allows a caller to provide a callback that the agent can invoke when it requires user approval.
+
+This approach is easy to use when the user and agent are in the same application context, such as a desktop application, where the application can show the approval request to the user and get their response from the callback before continuing the agent run.
+
+This approach does not work well for cases where the agent is hosted in a remote service, and where there is no user available to provide the approval in the same application context.
+For cases like this, the agent needs to be suspended, and a network response must be sent to the client app. After the user provides their approval, the client app must call the service that hosts the agent again, with the user's decision, and the agent needs to be resumed.  However, with a callback, the agent is deep in the call stack and cannot be suspended or resumed like this.
+
+```csharp
+class AgentRunOptions
+{
+    public Func<ApprovalRequestContent, Task<ApprovalResponseContent>>? ApprovalCallback { get; set; }
+}
+
+agent.RunAsync("Please book me a flight for Friday to Paris.", thread, new AgentRunOptions
+{
+    ApprovalCallback = async (approvalRequest) =>
+    {
+        // Show the approval request to the user in the appropriate format.
+        // The user can then approve or reject the request.
+        // The optional FunctionCallContent can be used to show the user what function the agent wants to call with the parameter set:
+        // approvalRequest.FunctionCall?.Arguments.
+
+        // If the user approves:
+        return true;
+    }
+});
+```
+
+### 3. Introduce new ApprovalRequestContent and ApprovalResponseContent types
+
+The agent would return an `ApprovalRequestContent` to the caller, which would then be responsible for getting approval from the user in whatever way is appropriate for the application.
+The caller would then invoke the agent again with an `ApprovalResponseContent` to the agent containing the user decision.
+
+When an agent returns an `ApprovalRequestContent`, the run is finished for the time being, and to continue, the agent must be invoked again with an `ApprovalResponseContent` on the same thread as the original request. This doesn't of course have to be the exact same thread object, but it should have the equivalent contents as the original thread, since the agent would have stored the `ApprovalRequestContent` in its thread state.
+
+The `ApprovalRequestContent` could contain an optional `FunctionCallContent` if the approval is for a function call, along with any additional information that the agent wants to provide to the user to help them make a decision.
+
+It is up to the agent to decide when and if a user approval is required, and therefore when to return an `ApprovalRequestContent`.
+
+`ApprovalRequestContent` and `ApprovalResponseContent` will not necessarily always map to a supported content type for the underlying service or agent thread storage.
+Specifically, when we are deciding in the IChatClient stack to ask for approval from the user, for a function call, this does not mean that the underlying ai service or
+service side thread type (where applicable) supports the concept of a function call approval request.  While we can store the approval requests and response in local
+threads, service managed threads won't necessarily support this.  For service managed threads, there will therefore be no long term record of the approval request in the chat history.
+We should however log approvals so that there is a trace of this for debugging and auditing purposes.
+
+Suggested Types:
+
+```csharp
+class ApprovalRequestContent : AIContent
+{
+    // An ID to uniquely identify the approval request/response pair.
+    public string Id { get; set; }
+
+    // An optional user targeted message to explain what needs to be approved.
+    public string? Text { get; set; }
+
+    // Optional: If the approval is for a function call, this will contain the function call content.
+    public FunctionCallContent? FunctionCall { get; set; }
+
+    public ApprovalResponseContent CreateApproval()
+    {
+        return new ApprovalResponseContent
+        {
+            Id = this.Id,
+            Approved = true,
+            FunctionCall = this.FunctionCall
+        };
+    }
+
+    public ApprovalResponseContent CreateRejection()
+    {
+        return new ApprovalResponseContent
+        {
+            Id = this.Id,
+            Approved = false,
+            FunctionCall = this.FunctionCall
+        };
+    }
+}
+
+class ApprovalResponseContent : AIContent
+{
+    // An ID to uniquely identify the approval request/response pair.
+    public string Id { get; set; }
+
+    // Indicates whether the user approved the request.
+    public bool Approved { get; set; }
+
+    // Optional: If the approval is for a function call, this will contain the function call content.
+    public FunctionCallContent? FunctionCall { get; set; }
+}
+
+var response = await agent.RunAsync("Please book me a flight for Friday to Paris.", thread);
+while (response.ApprovalRequests.Count > 0)
+{
+    List<ChatMessage> messages = new List<ChatMessage>();
+    foreach (var approvalRequest in response.ApprovalRequests)
+    {
+        // Show the approval request to the user in the appropriate format.
+        // The user can then approve or reject the request.
+        // The optional FunctionCallContent can be used to show the user what function the agent wants to call with the parameter set:
+        // approvalRequest.FunctionCall?.Arguments.
+        // The Text property of the ApprovalRequestContent can also be used to show the user any additional textual context about the request.
+    
+        // If the user approves:
+        messages.Add(new ChatMessage(ChatRole.User, [approvalRequest.CreateApproval()]));
+    }
+
+    // Get the next response from the agent.
+    response = await agent.RunAsync(messages, thread);
+}
+
+class AgentRunResponse
+{
+    ...
+
+    // A new property on AgentRunResponse to aggregate the ApprovalRequestContent items from
+    // the response messages (Similar to the Text property).
+    public IEnumerable<ApprovalRequestContent> ApprovalRequests { get; set; }
+
+    ...
+}
+```
+
+### 4. Introduce new Container UserInputRequestContent and UserInputResponseContent types
+
+This approach is similar to the `ApprovalRequestContent` and `ApprovalResponseContent` types, but is more generic and can be used for any type of user input request, not just approvals.
+
+There is some ambiguity with this approach. When using an LLM based agent the LLM may return a text response about missing user input.
+E.g the LLM may need to invoke a function but the user did not supply all necessary information to fill out all arguments.
+Typically an LLM would just respond with a text message asking the user for the missing information.
+In this case, the message is not distinguishable from any other result message, and therefore cannot be returned to the caller as a `UserInputRequestContent`, even though it is conceptually a type of unstructured user input request. Ultimately our types are modeled to make it easy for callers to decide on the right way to represent this to users. E.g. is it just a regular message to show to users, or do we need a special UX for it.
+
+Suggested Types:
+
+```csharp
+class UserInputRequestContent : AIContent
+{
+    // An ID to uniquely identify the approval request/response pair.
+    public string ApprovalId { get; set; }
+
+    // DecisionTarget could contain:
+    // FunctionCallContent: The function call that the agent wants to invoke.
+    // TextContent: Text that describes the question for that the user should answer.
+    object? DecisionTarget { get; set; } // Anything else the user may need to make a decision about.
+
+    // Possible InputFormat subclasses:
+    //   SchemaInputFormat: Contains a schema for the user input.
+    //   ApprovalInputFormat: Indicates that the user needs to approve something.
+    //   FreeformTextInputFormat: Indicates that the user can provide freeform text input.
+    // Other formats can be added as needed, e.g. cards when using activity protocol.
+    public InputFormat InputFormat { get; set; } // How the user should provide input (e.g., form, options, etc.).
+}
+
+class UserInputResponseContent : AIContent
+{
+    // An ID to uniquely identify the approval request/response pair.
+    public string ApprovalId { get; set; }
+
+    // Possible UserInputResult subclasses:
+    //   SchemaInputResult: Contains the structured data provided by the user.
+    //   ApprovalResult: Contains a bool with approved / rejected.
+    //   FreeformTextResult: Contains the freeform text input provided by the user.
+    public UserInputResult Result { get; set; } // The user input.
+
+    public object? DecisionTarget { get; set; } // A copy of the DecisionTarget from the UserInputRequestContent, if applicable.
+}
+
+var response = await agent.RunAsync("Please book me a flight for Friday to Paris.", thread);
+while (response.UserInputRequests.Any())
+{
+    List<ChatMessage> messages = new List<ChatMessage>();
+    foreach (var userInputRequest in response.UserInputRequests)
+    {
+        // Show the user input request to the user in the appropriate format.
+        // The DecisionTarget can be used to show the user what function the agent wants to call with the parameter set.
+        // The InputFormat property can be used to determine the type of UX when allowing users to provide input.
+
+        if (userInputRequest.InputFormat is ApprovalInputFormat approvalInputFormat)
+        {
+            // Here we need to show the user an approval request.
+            // We can use the DecisionTarget to show e.g. the function call that the agent wants to invoke.
+            // The user can then approve or reject the request.
+    
+            // If the user approves:
+            var approvalMessage = new ChatMessage(ChatRole.User, new UserInputResponseContent {  
+                ApprovalId = userInputRequest.ApprovalId,
+                Result = new ApprovalResult { Approved = true },
+                DecisionTarget = userInputRequest.DecisionTarget
+            });
+            messages.Add(approvalMessage);
+        }
+        else
+        {
+            throw new NotSupportedException("Unsupported InputFormat type.");
+        }
+    }
+
+    // Get the next response from the agent.
+    response = await agent.RunAsync(messages, thread);
+}
+
+class AgentRunResponse
+{
+    ...
+
+    // A new property on AgentRunResponse to aggregate the UserInputRequestContent items from
+    // the response messages (Similar to the Text property).
+    public IReadOnlyList<UserInputRequestContent> UserInputRequests { get; set; }
+
+    ...
+}
+```
+
+### 5. Introduce new Base UserInputRequestContent and UserInputResponseContent types
+
+This approach is similar to option 4, but the `UserInputRequestContent` and `UserInputResponseContent` types are base classes rather than generic container types.
+
+Suggested Types:
+
+```csharp
+class UserInputRequestContent : AIContent
+{
+    // An ID to uniquely identify the approval request/response pair.
+    public string Id { get; set; }
+}
+
+class UserInputResponseContent : AIContent
+{
+    // An ID to uniquely identify the approval request/response pair.
+    public string Id { get; set; }
+}
+
+// -----------------------------------
+// Used for approving a function call.
+class FunctionApprovalRequestContent : UserInputRequestContent
+{
+    // Contains the function call that the agent wants to invoke.
+    public FunctionCallContent FunctionCall { get; set; }
+
+    public ApprovalResponseContent CreateApproval()
+    {
+        return new ApprovalResponseContent
+        {
+            Id = this.Id,
+            Approved = true,
+            FunctionCall = this.FunctionCall
+        };
+    }
+
+    public ApprovalResponseContent CreateRejection()
+    {
+        return new ApprovalResponseContent
+        {
+            Id = this.Id,
+            Approved = false,
+            FunctionCall = this.FunctionCall
+        };
+    }
+}
+class FunctionApprovalResponseContent : UserInputResponseContent
+{
+    // Indicates whether the user approved the request.
+    public bool Approved { get; set; }
+
+    // Contains the function call that the agent wants to invoke.
+    public FunctionCallContent FunctionCall { get; set; }
+}
+
+// --------------------------------------------------
+// Used for approving a request described using text.
+class TextApprovalRequestContent : UserInputRequestContent
+{
+    // A user targeted message to explain what needs to be approved.
+    public string Text { get; set; }
+}
+class TextApprovalResponseContent : UserInputResponseContent
+{
+    // Indicates whether the user approved the request.
+    public bool Approved { get; set; }
+}
+
+// ------------------------------------------------
+// Used for providing input in a structured format.
+class StructuredDataInputRequestContent : UserInputRequestContent
+{
+    // A user targeted message to explain what is being requested.
+    public string? Text { get; set; }
+
+    // Contains the schema for the user input.
+    public JsonElement Schema { get; set; }
+}
+class StructuredDataInputResponseContent : UserInputResponseContent
+{
+    // Contains the structured data provided by the user.
+    public JsonElement StructuredData { get; set; }
+}
+
+var response = await agent.RunAsync("Please book me a flight for Friday to Paris.", thread);
+while (response.UserInputRequests.Any())
+{
+    List<ChatMessage> messages = new List<ChatMessage>();
+    foreach (var userInputRequest in response.UserInputRequests)
+    {
+        if (userInputRequest is FunctionApprovalRequestContent approvalRequest)
+        {
+            // Here we need to show the user an approval request.
+            // We can use the FunctionCall property to show e.g. the function call that the agent wants to invoke.
+            // If the user approves:
+            messages.Add(new ChatMessage(ChatRole.User, approvalRequest.CreateApproval()));
+        }
+    }
+
+    // Get the next response from the agent.
+    response = await agent.RunAsync(messages, thread);
+}
+
+class AgentRunResponse
+{
+    ...
+
+    // A new property on AgentRunResponse to aggregate the UserInputRequestContent items from
+    // the response messages (Similar to the Text property).
+    public IEnumerable<UserInputRequestContent> UserInputRequests { get; set; }
+
+    ...
+}
+```
+
+## Decision Outcome
+
+Chosen option 5.
+
+## Appendices
+
+### ChatClientAgent Approval Process Flow
+
+1. User passes a User message to the agent with a request.
+1. Agent calls IChatClient with any functions registered on the agent.
+   (IChatClient has FunctionInvokingChatClient)
+1. Model responds with FunctionCallContent indicating function calls required.
+1. FunctionInvokingChatClient decorator identifies any function calls that require user approval and returns an FunctionApprovalRequestContent.
+   (If there are multiple parallel function calls, all function calls will be returned as FunctionApprovalRequestContent even if only some require approval.)
+1. Agent updates the thread with the FunctionApprovalRequestContent (or this may have already been done by a service threaded agent).
+1. Agent returns the FunctionApprovalRequestContent to the caller which shows it to the user in the appropriate format.
+1. User (via caller) invokes the agent again with FunctionApprovalResponseContent.
+1. Agent adds the FunctionApprovalResponseContent to the thread.
+1. Agent calls IChatClient with the provided FunctionApprovalResponseContent.
+1. Agent invokes IChatClient with FunctionApprovalResponseContent and the FunctionInvokingChatClient decorator identifies the response as an approval for the function call.
+   Any rejected approvals are converted to FunctionResultContent with a message indicating that the function invocation was denied.
+   Any approved approvals are executed by the FunctionInvokingChatClient decorator.
+1. FunctionInvokingChatClient decorator passes the FunctionCallContent and FunctionResultContent for the approved and rejected function calls to the model.
+1. Model responds with the result.
+1. FunctionInvokingChatClient returns the FunctionCallContent, FunctionResultContent, and the result message to the agent.
+1. Agent responds to caller with the same messages and updates the thread with these as well.
+
+### CustomAgent Approval Process Flow
+
+1. User passes a User message to the agent with a request.
+1. Agent adds this message to the thread.
+1. Agent executes various steps.
+1. Agent encounters a step for which it requires user input to continue.
+1. Agent responds with an UserInputRequestContent and also adds it to its thread.
+1. User (via caller) invokes the agent again with UserInputResponseContent.
+1. Agent adds the UserInputResponseContent to the thread.
+1. Agent responds to caller with result message and thread is updated with the result message.
+
+### Sequence Diagram: FunctionInvokingChatClient with built in Approval Generation
+
+This is a ChatClient Approval Stack option has been proven to work via a proof of concept implementation.
+
+```mermaid
+---
+title: Multiple Functions with partial approval
+---
+
+sequenceDiagram
+    note right of Developer: Developer asks question with two functions.
+    Developer->>+FunctionInvokingChatClient: What is the special soup today?<br/>[GetMenu, GetSpecials]
+    FunctionInvokingChatClient->>+ResponseChatClient: What is the special soup today?<br/>[GetMenu, GetSpecials]
+
+    ResponseChatClient-->>-FunctionInvokingChatClient: [FunctionCallContent(GetMenu)],<br/>[FunctionCallContent(GetSpecials)]
+    note right of FunctionInvokingChatClient: FICC turns FunctionCallContent<br/>into FunctionApprovalRequestContent
+    FunctionInvokingChatClient->>+Developer: [FunctionApprovalRequestContent(GetMenu)]<br/>[FunctionApprovalRequestContent(GetSpecials)]
+
+    note right of Developer:Developer asks user for approval
+    Developer->>+FunctionInvokingChatClient: [FunctionApprovalRequestContent(GetMenu, approved=false)]<br/>[FunctionApprovalRequestContent(GetSpecials, approved=true)]
+    note right of FunctionInvokingChatClient:FunctionInvokingChatClient executes the approved<br/>function and generates a failed FunctionResultContent<br/>for the rejected one, before invoking the model again.
+    FunctionInvokingChatClient->>+ResponseChatClient: What is the special soup today?<br/>[FunctionCallContent(GetMenu)],<br/>[FunctionCallContent(GetSpecials)],<br/>[FunctionResultContent(GetMenu, Function invocation denied")]<br/>[FunctionResultContent(GetSpecials, "Special Soup: Clam Chowder...")]
+
+    ResponseChatClient-->>-FunctionInvokingChatClient: [TextContent("The specials soup is...")]
+    FunctionInvokingChatClient->>+Developer: [FunctionCallContent(GetMenu)],<br/>[FunctionCallContent(GetSpecials)],<br/>[FunctionResultContent(GetMenu, Function invocation denied")]<br/>[FunctionResultContent(GetSpecials, "Special Soup: Clam Chowder...")]<br/>[TextContent("The specials soup is...")]
+```
+
+### Sequence Diagram: Post FunctionInvokingChatClient ApprovalGeneratingChatClient - Multiple function calls with partial approval
+
+This is a discarded ChatClient Approval Stack option, but is included here for reference.
+
+```mermaid
+---
+title: Multiple Functions with partial approval
+---
+
+sequenceDiagram
+    note right of Developer: Developer asks question with two functions.
+    Developer->>+FunctionInvokingChatClient: What is the special soup today? [GetMenu, GetSpecials]
+    FunctionInvokingChatClient->>+ApprovalGeneratingChatClient: What is the special soup today? [GetMenu, GetSpecials]
+    ApprovalGeneratingChatClient->>+ResponseChatClient: What is the special soup today? [GetMenu, GetSpecials]
+
+    ResponseChatClient-->>-ApprovalGeneratingChatClient: [FunctionCallContent(GetMenu)],<br/>[FunctionCallContent(GetSpecials)]
+    ApprovalGeneratingChatClient-->>-FunctionInvokingChatClient: [FunctionApprovalRequestContent(GetMenu)],<br/>[FunctionApprovalRequestContent(GetSpecials)]
+    FunctionInvokingChatClient-->>-Developer: [FunctionApprovalRequestContent(GetMenu)]<br/>[FunctionApprovalRequestContent(GetSpecials)]
+
+    note right of Developer: Developer approves one function call and rejects the other.
+    Developer->>+FunctionInvokingChatClient: [FunctionApprovalResponseContent(GetMenu, approved=true)]<br/>[FunctionApprovalResponseContent(GetSpecials, approved=false)]
+    FunctionInvokingChatClient->>+ApprovalGeneratingChatClient: [FunctionApprovalResponseContent(GetMenu, approved=true)]<br/>[FunctionApprovalResponseContent(GetSpecials, approved=false)]
+
+    note right of FunctionInvokingChatClient: ApprovalGeneratingChatClient only returns FunctionCallContent<br/>for approved FunctionApprovalResponseContent.
+    ApprovalGeneratingChatClient-->>-FunctionInvokingChatClient: [FunctionCallContent(GetMenu)]
+    note right of FunctionInvokingChatClient: FunctionInvokingChatClient has to also include all<br/>FunctionApprovalResponseContent in the new downstream request.
+    FunctionInvokingChatClient->>+ApprovalGeneratingChatClient: [FunctionResultContent(GetMenu, "mains.... deserts...")]<br/>[FunctionApprovalResponseContent(GetMenu, approved=true)]<br/>[FunctionApprovalResponseContent(GetSpecials, approved=false)]
+
+    note right of ApprovalGeneratingChatClient: ApprovalGeneratingChatClient now throws away<br/>approvals for executed functions, and creates<br/>failed FunctionResultContent for denied function calls.
+    ApprovalGeneratingChatClient->>+ResponseChatClient: [FunctionResultContent(GetMenu, "mains.... deserts...")]<br/>[FunctionResultContent(GetSpecials, "Function invocation denied")]
+```
+
+### Sequence Diagram: Pre FunctionInvokingChatClient ApprovalGeneratingChatClient - Multiple function calls with partial approval
+
+This is a discarded ChatClient Approval Stack option, but is included here for reference.
+
+It doesn't work for the scenario where we have multiple function calls for the same function in serial with different arguments.
+
+Flow:
+
+- AGCC turns AIFunctions into AIFunctionDefinitions (not invocable) and FICC ignores these.
+- We get back a FunctionCall for one of these and it gets approved.
+- We invoke the FICC again, this time with an AIFunction.
+- We call the service with the FCC and FRC.
+- We get back a new Function call for the same function again with different arguments.
+- Since we were passed an AIFunction instead of an AIFunctionDefinition, we now incorrectly execute this FC without approval.
+
+```mermaid
+---
+title: Multiple Functions with partial approval
+---
+
+sequenceDiagram
+    note right of Developer: Developer asks question with two functions.
+    Developer->>+ApprovalGeneratingChatClient: What is the special soup today? [GetMenu, GetSpecials]
+    note right of ApprovalGeneratingChatClient: AGCC marks functions as not-invocable
+    ApprovalGeneratingChatClient->>+FunctionInvokingChatClient: What is the special soup today?<br/>[GetMenu(invocable=false)]<br/>[GetSpecials(invocable=false)]
+    FunctionInvokingChatClient->>+ResponseChatClient: What is the special soup today?<br/>[GetMenu(invocable=false)]<br/>[GetSpecials(invocable=false)]
+
+    ResponseChatClient-->>-FunctionInvokingChatClient: [FunctionCallContent(GetMenu)],<br/>[FunctionCallContent(GetSpecials)]
+    note right of FunctionInvokingChatClient: FICC doesn't invoke functions since they are not invocable.
+    FunctionInvokingChatClient-->>-ApprovalGeneratingChatClient: [FunctionCallContent(GetMenu)],<br/>[FunctionCallContent(GetSpecials)]
+    note right of ApprovalGeneratingChatClient: AGCC turns functions into approval requests
+    ApprovalGeneratingChatClient-->>-Developer: [FunctionApprovalRequestContent(GetMenu)]<br/>[FunctionApprovalRequestContent(GetSpecials)]
+
+    note right of Developer: Developer approves one function call and rejects the other.
+    Developer->>+ApprovalGeneratingChatClient: [FunctionApprovalResponseContent(GetMenu, approved=true)]<br/>[FunctionApprovalResponseContent(GetSpecials, approved=false)]
+    note right of ApprovalGeneratingChatClient: AGCC turns turns approval requests<br/>into FCC or failed function calls
+    ApprovalGeneratingChatClient->>+FunctionInvokingChatClient: [FunctionCallContent(GetMenu)]<br/>[FunctionCallContent(GetSpecials)<br/>[FunctionResultContent(GetSpecials, "Function invocation denied"))]
+    note right of FunctionInvokingChatClient: FICC invokes GetMenu since it's the only remaining one.
+    FunctionInvokingChatClient->>+ResponseChatClient: [FunctionCallContent(GetMenu)]<br/>[FunctionResultContent(GetMenu, "mains.... deserts...")]<br/>[FunctionCallContent(GetSpecials)<br/>[FunctionResultContent(GetSpecials, "Function invocation denied"))]
+
+    ResponseChatClient-->>-FunctionInvokingChatClient: [FunctionCallContent(GetMenu)]<br/>[FunctionResultContent(GetMenu, "mains.... deserts...")]<br/>[FunctionCallContent(GetSpecials)<br/>[FunctionResultContent(GetSpecials, "Function invocation denied"))]<br/>[TextContent("The specials soup is...")]
+    FunctionInvokingChatClient-->>-ApprovalGeneratingChatClient: [FunctionCallContent(GetMenu)]<br/>[FunctionResultContent(GetMenu, "mains.... deserts...")]<br/>[FunctionCallContent(GetSpecials)<br/>[FunctionResultContent(GetSpecials, "Function invocation denied"))]<br/>[TextContent("The specials soup is...")]
+    ApprovalGeneratingChatClient-->>-Developer: [FunctionCallContent(GetMenu)]<br/>[FunctionResultContent(GetMenu, "mains.... deserts...")]<br/>[FunctionCallContent(GetSpecials)<br/>[FunctionResultContent(GetSpecials, "Function invocation denied"))]<br/>[TextContent("The specials soup is...")]
+```

docs/decisions/0008-python-subpackages.md

@@ -0,0 +1,92 @@
+---
+status: accepted
+contact: eavanvalkenburg
+date: 2025-09-19
+deciders: eavanvalkenburg, markwallace-microsoft,  ekzhu, sphenry, alliscode
+consulted: taochenosu, moonbox3, dmytrostruk, giles17
+---
+
+# Python Subpackages Design
+
+## Context and Problem Statement
+
+The goal is to design a subpackage structure for the Python agent framework that balances ease of use, maintainability, and scalability. How can we organize the codebase to facilitate the development and integration of connectors while minimizing complexity for users?
+
+## Decision Drivers
+
+- Ease of use for developers
+- Maintainability of the codebase
+- User experience for installing and using the integrations
+- Clear lifecycle management for integrations
+- Minimize non-GA dependencies in the main package
+
+## Considered Options
+
+1. One subpackage per vendor, so a `google` package that contains all Google related connectors, such as `GoogleChatClient`, `BigQueryCollection`, etc.
+    * Pros:
+        - fewer packages to manage, publish and maintain
+        - easier for users to find and install the right package.
+        - users that work primarily with one platform have a single package to install.
+    * Cons:
+        - larger packages with more dependencies
+        - larger installation sizes
+        - more difficult to version, since some parts may be GA, while other are in preview.
+2. One subpackage per connector, so a i.e. `google_chat` package, a i.e. `google_bigquery` package, etc.
+    * Pros:
+        - smaller packages with fewer dependencies
+        - smaller installation sizes
+        - easy to version and do lifecycle management on
+    * Cons:
+        - more packages to manage, register, publish and maintain
+        - more extras, means more difficult for users to find and install the right package.
+3. Group connectors by vendor and maturity, so that you can graduate something from the i.e. the `google-preview` package to the `google` package when it becomes GA.
+    * Pros:
+        - fewer packages to manage, publish and maintain
+        - easier for users to find and install the right package.
+        - users that work primarily with one platform have a single package to install.
+        - clear what the status is based on extra name
+    * Cons:
+        - moving something from one to the other might be a breaking change
+        - still larger packages with more dependencies
+    It could be mitigated that the `google-preview` package is still imported from `agent_framework.google`, so that the import path does not change, when something graduates, but it is still a clear choice for users to make. And we could then have three extras on that package, `google`, `google-preview` and `google-all` to make it easy to install the right package or just all.
+4. Group connectors by vendor and type, so that you have a `google-chat` package, a `google-data` package, etc.
+    * Pros:
+        - smaller packages with fewer dependencies
+        - smaller installation sizes
+    * Cons:
+        - more packages to manage, register, publish and maintain
+        - more extras, means more difficult for users to find and install the right package.
+        - still keeps the lifecycle more difficult, since some parts may be GA, while other are in preview.
+5. Add `meta`-extras, that combine different subpackages as one extra, so we could have a `google` extra that includes `google-chat`, `google-bigquery`, etc.
+    * Pros:
+        - easier for users on a single platform
+    * Cons:
+        - more packages to manage, register, publish and maintain
+        - more extras, means more difficult for users to find and install the right package.
+        - makes developer package management more complex, because that meta-extra will include both GA and non-GA packages, so during dev they could use that, but then during prod they have to figure out which one they actually need and make a change in their dependencies, leading to mismatches between dev and prod.
+6. Make all imports happen from `agent_framework.connectors` (or from two or three groups `agent_framework.chat_clients`, `agent_framework.context_providers`, or something similar) while the underlying code comes from different packages.
+    * Pros:
+        - best developer experience, since all imports are from the same place and it is easy to find what you need, and we can raise a meaningfull error with which extra to install.
+        - easier for users to find and install the right package.
+    * Cons:
+        - larger overhead in maintaining the `__init__.py` files that do the lazy loading and error handling.
+        - larger overhead in package management, since we have to ensure that the main package.
+7. Subpackage existence will be based off status of dependencies and/or possibilities of a external support mechanism. What this means is that:
+    - Integrations that need non-GA dependencies will be subpackages, so that we can avoid having non-GA dependencies in the main package.
+    - Integrations where the AF-code is still experimental, preview or release candidate will be subpackages, so that we can avoid having non-GA code in the main package and we can version those packages properly.
+    - Integrations that are outside Microsoft and where we might not always be able to fast-follow breaking changes, will stay as subpackages, to provide some isolation and to be able to version them properly.
+    - Integrations that are mature and that have released (GA) dependencies and or features on the service side will be moved into the main package, the dependencies of those packages will stay installable under the same `extra` name, so that users do not have to change anything, and we then remove the subpackage itself.
+    - All subpackage imports in the code should be from a stable place, mostly vendor-based, so that when something moves from a subpackage to the main package, the import path does not change, so `from agent_framework.google import GoogleChatClient` will always work, even if it moves from the `agent-framework-google` package to the main `agent-framework` package.
+    - The imports in those vendor namespaces (these won't be actual python namespaces, just the folders with a __init__.py file and any code) will do lazy loading and raise a meaningful error if the subpackage or dependencies are not installed, so that users know which extra to install with ease.
+    - On a case by case basis we can decide to create additional `extras`, that combine multiple subpackages into one extra, so that users that work primarily with one platform can install everything they need with a single extra, for instance you can install with the `agent-framework[azure-purview]` extra that only implement a Azure Purview Middleware, or you can install with the `agent-framework[azure]` extra that includes all Azure related connectors, like `purview`, `content safety` and others (all examples, not actual packages (yet)), regardless of where the code sits, these should always be importable from `agent_framework.azure`.
+    - Subpackage naming should also follow this, so in principle a package name is `<vendor/folder>-<feature/brand>`, so `google-gemini`, `azure-purview`, `microsoft-copilotstudio`, etc. For smaller vendors, with less likely to have a multitude of connectors, we can skip the feature/brand part, so `mem0`, `redis`, etc.
+
+## Decision Outcome
+
+Option 7: This provides us a good balance between developer experience, user experience, package management and maintenance, while also allowing us to evolve the package structure over time as dependencies and features mature. And it ensures the main package, installed without extras does not include non-GA dependencies or code, extras do not carry that guarantee, for both the code and the dependencies.
+
+# Microsoft vs Azure packages
+Another consideration is for Microsoft, since we have a lot of Azure services, but also other Microsoft services, such as Microsoft Copilot Studio, and potentially other services in the future, and maybe Foundry also will be marketed separate from Azure at some point. We could also have both a `microsoft` and an `azure` package, where the `microsoft` package contains all Microsoft services, excluding Azure, while the `azure` package only contains Azure services. Only applicable for the variants where we group by vendor, including with meta packages.
+
+## Decision Outcome
+Azure and Microsoft will be the two vendor folders for Microsoft services, so Copilot Studio will be imported from `agent_framework.microsoft`, while Foundry, Azure OpenAI and other Azure services will be imported from `agent_framework.azure`.

docs/decisions/0010-ag-ui-support.md

@@ -0,0 +1,95 @@
+---
+status: accepted
+contact: javiercn
+date: 2025-10-29
+deciders: javiercn, DeagleGross, moonbox3, markwallace-microsoft
+consulted: Agent Framework team
+informed: .NET community
+---
+
+# AG-UI Protocol Support for .NET Agent Framework
+
+## Context and Problem Statement
+
+The .NET Agent Framework needed a standardized way to enable communication between AI agents and user-facing applications with support for streaming, real-time updates, and bidirectional communication. Without AG-UI protocol support, .NET agents could not interoperate with the growing ecosystem of AG-UI-compatible frontends and agent frameworks (LangGraph, CrewAI, Pydantic AI, etc.), limiting the framework's adoption and utility.
+
+The AG-UI (Agent-User Interaction) protocol is an open, lightweight, event-based protocol that addresses key challenges in agentic applications including streaming support for long-running agents, event-driven architecture for nondeterministic behavior, and protocol interoperability that complements MCP (tool/context) and A2A (agent-to-agent) protocols.
+
+## Decision Drivers
+
+- Need for streaming communication between agents and client applications
+- Requirement for protocol interoperability with other AI frameworks
+- Support for long-running, multi-turn conversation sessions
+- Real-time UI updates for nondeterministic agent behavior
+- Standardized approach to agent-to-UI communication
+- Framework abstraction to protect consumers from protocol changes
+
+## Considered Options
+
+1. **Implement AG-UI event types as public API surface** - Expose AG-UI event models directly to consumers
+2. **Use custom AIContent types for lifecycle events** - Create new content types (RunStartedContent, RunFinishedContent, RunErrorContent)
+3. **Current approach** - Internal event types with framework-native abstractions
+
+## Decision Outcome
+
+Chosen option: "Current approach with internal event types and framework-native abstractions", because it:
+
+- Protects consumers from protocol changes by keeping AG-UI events internal
+- Maintains framework abstractions through conversion at boundaries
+- Uses existing framework types (AgentRunResponseUpdate, ChatMessage) for public API
+- Focuses on core text streaming functionality
+- Leverages existing properties (ConversationId, ResponseId, ErrorContent) instead of custom types
+- Provides bidirectional client and server support
+
+### Implementation Details
+
+**In Scope:**
+1. **Client-side AG-UI consumption** (`Microsoft.Agents.AI.AGUI` package)
+   - `AGUIAgent` class for connecting to remote AG-UI servers
+   - `AGUIAgentThread` for managing conversation threads
+   - HTTP/SSE streaming support
+   - Event-to-framework type conversion
+
+2. **Server-side AG-UI hosting** (`Microsoft.Agents.AI.Hosting.AGUI.AspNetCore` package)
+   - `MapAGUIAgent` extension method for ASP.NET Core
+   - Server-Sent Events (SSE) response formatting
+   - Framework-to-event type conversion
+   - Agent factory pattern for per-request instantiation
+
+3. **Text streaming events**
+   - Lifecycle events: `RunStarted`, `RunFinished`, `RunError`
+   - Text message events: `TextMessageStart`, `TextMessageContent`, `TextMessageEnd`
+   - Thread and run ID management via `ConversationId` and `ResponseId`
+
+### Key Design Decisions
+
+1. **Event Models as Internal Types** - AG-UI event types are internal with conversion via extension methods; public API uses the existing types in Microsoft.Extensions.AI as those are the abstractions people are familiar with
+
+2. **No Custom Content Types** - Run lifecycle communicated through existing `ChatResponseUpdate` properties (`ConversationId`, `ResponseId`) and standard `ErrorContent` type
+
+3. **Agent Factory Pattern** - `MapAGUIAgent` uses factory function `(messages) => AIAgent` to allow request-specific agent configuration supporting multi-tenancy
+
+4. **Bidirectional Conversion Architecture** - Symmetric conversion logic in shared namespace compiled into both packages for server (`AgentRunResponseUpdate` → AG-UI events) and client (AG-UI events → `AgentRunResponseUpdate`)
+
+5. **Thread Management** - `AGUIAgentThread` stores only `ThreadId` with thread ID communicated via `ConversationId`; applications manage persistence for parity with other implementations and to be compliant with the protocol. Future extensions will support having the server manage the conversation.
+
+6. **Custom JSON Converter** - Uses custom polymorphic deserialization via `BaseEventJsonConverter` instead of built-in System.Text.Json support to handle AG-UI protocol's flexible discriminator positioning
+
+### Consequences
+
+**Positive:**
+- .NET developers can consume AG-UI servers from any framework
+- .NET agents accessible from any AG-UI-compatible client
+- Standardized streaming communication patterns
+- Protected from protocol changes through internal implementation
+- Symmetric conversion logic between client and server
+- Framework-native public API surface
+
+**Negative:**
+- Custom JSON converter required (internal implementation detail)
+- Shared code uses preprocessor directives (`#if ASPNETCORE`)
+- Additional abstraction layer between protocol and public API
+
+**Neutral:**
+- Initial implementation focused on text streaming
+- Applications responsible for thread persistence

docs/design/README.md

@@ -1,103 +0,0 @@
-# Agent Framework Design Doc
-
-What values does the framework provide?
-
-- A set of configurable, extensible and high-quality components (e.g., model clients, tools, MCP servers and memory).
-- An easy path for deploying, securing and scaling applications, both locally and in the cloud.
-- Integration with tools for monitoring, debugging, evaluation and optimization, both locally and in the cloud.
-- A community of developers and users for support, ideas, and contributions, benefiting everyone in the ecosystem.
-
-What is this document?
-
-- An overview of the new framework.
-- Defining the major elements of the framework and their relationships.
-- Detailed design of each element and its implementation will be in a separate document.
-
-## Core Data Types
-
-To unify the interaction between components, we define a set of core
-data types that are used throughout the framework.
-
-See [Core Data Types](types.md) for more details.
-
-## Components
-
-A component is a class that provides a specific functionality and can be used
-independently by applications.
-There are two types of components in the framework: agent components and agents. Agent components are the building blocks of agents, while agents are
-the higher-level components, and can be composed from agent components
-and other agents (as in workflows).
-
-The framework defines the following components. Follow the links to
-find the design details of each component:
-
-- Agent Components:
-  - [Model Client](models.md)
-  - [Vector Store and Embedding Client](vector-stores.md)
-  - [Tool](tools.md)
-  - [MCP Server](mcp-servers.md)
-  - [Context Provider (memory, RAG, etc.)](context_providers.md)
-  - [Thread](threads.md)
-  - [Guardrail](guardrails.md)
-- Agent and Workflow:
-  - [Agent](agents.md)
-  - [Workflow](workflows.md)
-
-### Composition
-
-Components can be composed to create complex components. For example,
-an agent can be composed from model clients, tools and memory,
-and a tool can be composed from an agent or a workflow.
-It is the responsibility of the framework to validate components
-and their composition.
-
-### Configuration
-
-A component can be created from a set of serializable configuration parameters,
-with the help of dependency injection to resolve non-serializable dependencies.
-
-### Relationships
-
-The following diagram shows the component relationship of the framework:
-
-```mermaid
-graph TD
-    Component[Component] --> |extends| Agent[Agent]
-    Agent --> |extends| Workflow[Workflow]
-    
-    Component --> |extends| ModelClient[Model Client]
-    Component --> |extends| VectorStore[Vector Store]
-    Component --> |extends| EmbeddingClient[Embedding Client]
-    Component --> |extends| Tool[Tool]
-    Component --> |extends| MCPServer[MCP Server]
-    Component --> |extends| ContextProvider[Context Provider]
-    Component --> |extends| Thread[Thread]
-    Component --> |extends| Guardrail[Guardrail]
-    
-    Agent --> |uses| uses1[Model Client]
-    Agent --> |uses| uses2[Thread]
-    Agent --> |uses| uses3[Tools and MCP Servers]
-    Agent --> |uses| uses4[Context Provider]
-    Agent --> |uses| uses5[Guardrail]
-    
-    Workflow --> |contains| contains[Child Agents]
-
-    ContextProvider --> |uses| uses5[Vector Store]
-    VectorStore --> |uses| uses6[Embedding Client]
-```
-
-## Deployment and Scaling
-
-[Deployment](deployment.md).
-
-## Observability and Monitoring
-
-[Observability](observability.md).
-
-## Evaluation
-
-[Evaluation](evaluation.md).
-
-## Optimization
-
-[Optimization](optimization.md).

docs/design/agents.md

@@ -1,512 +0,0 @@
-# Agents
-
-An agent is a component that processes messages in a thread and returns a result.
-
-During its handling of messages, an agent may:
-
-- Use model client to process messages,
-- Use thread to keep track of the interaction with the model,
-- Invoke tools or MCP servers, and
-- Retrieve and store data through memory.
-
-It is up to the implementation of the agent class to decide how these components are used.
-
-__An important design goal of the framework is to ensure the developer experience
-of creating custom agent is as easy as possible.__ Existing frameworks
-have made "kitchen-sink" agents that are hard to understand and maintain.
-
-An agent might not use the components provided by the framework to implement
-the agent interface.
-Azure AI Agent is an example of such agent: its implementation is
-backed by the Azure AI Agent Service.
-
-The framework provides a set of pre-built agents:
-
-- `ChatCompletionAgent`: an agent that uses a chat-completion model to process messages
-and use thread, memory, tools and MCP servers in a configurable way. __If we can make
-custom agents easy to implement, we can remove this agent.__
-- `AzureAIAgent`: an agent that is backed by Azure AI Agent Service.
-- `ResponsesAgent`: an agent that is backed by OpenAI's Responses API.
-- `A2AAgent`: an agent that is backed by the [A2A Protocol](https://google.github.io/A2A/documentation/).
-
-## `Agent` base class
-
-```python
-TInThread = TypeVar("TInThread", bound="AgentThread", contravariant=True)
-TNewThread = TypeVar("TOutThread", bound="AgentThread", covariant=True)
-
-class Agent(ABC, Generic[TInThread, TNewThread]):
-    """The base class for all agents in the framework."""
-
-    @abstractmethod
-    async def run(
-        self, 
-        messages: list[Message],
-        thread: TInThread,
-        context: RunContext,
-    ) -> Result:
-        """The method to run the agent on a thread of messages, and return the result.
-
-        Args:
-            messages: The list of new messages to process that have not been added
-                to the thread yet. The agent may use these messages and append
-                new messages to the thread as part of its processing.
-            thread: The thread of messages to process: it may be a local thread
-                or a stub thread that is backed by a remote service.
-            context: The context for the current invocation of the agent, providing
-                access to the event channel, and human-in-the-loop (HITL) features.
-        
-        Returns:
-            The result of running the agent, which includes the final response.
-        """
-        ...
-    
-    @classmethod
-    @abstractmethod
-    async def create_thread(self) -> TNewThread:
-        """Create a new thread for the agent to use.
-
-        Returns:
-            A new thread that is compatible with the agent.
-        """
-        ...
-
-
-@dataclass
-class RunContext:
-    """The context for the current invocation of the agent."""
-
-    event_handler: EventHandler | Callable[[Message], Awaitable[None]]
-    """The event consumer for handling events emitted by the agent. Could be
-    a callable that takes a message and returns an awaitable, or an instance of
-    `EventHandler` that handles events emitted by the agent."""
-
-    user_input_source: UserInputSource
-    """The user input source for requesting for user input during the agent run."""
-
-    ... # Other fields, could be extended to include more for application-specific needs.
-
-
-@dataclass
-class Result:
-    """The result of running an agent."""
-    final_response: Message
-    ... # Other fields, could be extended to include more for application-specific needs.
-```
-
-## `ToolCallingAgent` example
-
-Here is an example of a custom agent that calls a tool and returns the result.
-The `ToolCallingAgent` implements the `Agent` base class and
-it implements the `run` method to process incoming messages and call tools if needed.
-
-```python
-
-TInThread = TypeVar("TInThread", bound="ChatMessageThread", contravariant=True)
-TNewThread = TypeVar("TOuthread", bound="ChatMessageThread", covariant=True)
-
-class ToolCallingAgent(Agent[TInThread, TNewThread]):
-    def __init__(
-        self, 
-        model_client: ModelClient,
-        tools: list[Tool],
-    ) -> None:
-        self.model_client = model_client
-        self.tools = tools
-
-    async def run(self, messages: list[Message], thread: TInThread, context: RunContext) -> Result:
-        # Apply the messages to the thread.
-        await thread.on_new_messages(messages)
-        # Create a response using the model client, passing the thread and context.
-        create_result = await self.model_client.create(thread.messages, context, tools=self.tools)
-        # Emit the event to notify the workflow consumer of a model response.
-        await context.emit(ModelResponseEvent(create_result))
-        if create_result.is_tool_call():
-            # Get user approval for the tool call through the context.
-            approval = await context.get_user_approval(create_result.tool_calls)
-            if not approval:
-                # ... return a canned response.
-            # Call the tools with the tool calls in the response.
-            tools = ... # Find the tool by name in the tools list.
-            tool_results = ... # Call the tool with the tool call arguments.
-            # Emit the event to notify the workflow consumer of a tool call.
-            await context.emit(ToolCallEvent(tool_result))
-            # Update the thread with the tool result.
-            await thread.on_new_messages(tool_result.to_messages())
-            # Return the tool result as the response.
-            return Result(
-                final_response=tool_result,
-            )
-        else: 
-            # Return the response as the result.
-            return Result(
-                final_response=create_result,
-            )
-    
-    @classmethod
-    async def create_thread(self) -> TNewThread:
-        """Create a new thread for the agent to use.
-        
-        NOTE: this could be part of a new base class for this type of agent.
-        """
-        return await ChatMessageThread.create()
-```
-
-Things to note in the implementation of the `run` method:
-- Orchestration of tools and model is completly customizable.
-- Components such as `thread` and `model_client` interacts smoothly with little boilerplate code.
-- The `context` parameter provides convenient access to the workflow run fixtures such as event channel.
-
-In practice, the developer likely will inherit from `ChatAgent` to
-customize the `run` method, so they don't need to implement the boilerplate code
-for creating a thread.
-
-An agent doesn't need to use components provided by the framework to implement the agent interface.
-
-For example, in a multi-agent workflow, we may need a verification agent in a using deterministic
-logic to critic another agent's response.
-
-```python
-class CriticAgent(ChatAgent):
-    def __init__(self) -> None:
-        self.verification_logic = ... # Some verification logic, e.g. a set of rules.
-
-    async def run(self, messages: list[Message], thread: ChatMessageThread, context: RunContext) -> Result:
-        # Use the verification logic to verify the messages.
-        is_verified = self.verification_logic.verify(messages)
-        if is_verified:
-            final_response = Message("The response is verified.")
-        else:
-            final_response = Message("The response is not verified.")
-        
-        return Result(
-            final_response=final_response,
-        )
-```
-
-## Run
-
-A _run_ is a single invocation of the agent or a workflow given a thread of messages.
-
-## Run agent
-
-Developer can instantiate a subclass of `Agent` directly using it's constructor, 
-and run it by calling the `run` method.
-
-```python
-@FunctionTool
-def my_tool(input: str) -> str:
-    return f"Tool result for {input}"
-
-model_client = OpenAIChatCompletionClient("gpt-4.1")
-agent = ToolCallingAgent(
-    model_client=model_client, 
-    tools=[my_tool],
-)
-
-# Create a thread for the current task.
-thread = await ChatMessageThread.create()
-
-# Create a context that uses a handler that prints emitted events to the console, 
-# and a user input source that reads from the console.
-context = RunContext(event_handler=ConsoleEventHandler(), user_input_source=ConsoleUserInputSource())
-
-# Run the agent with the thread and context.
-result = await agent.run([Message("Can you find the file 'foo.txt' for me?")], thread, context)
-```
-
-## User session
-
-A user session is a logical concept which involves a sequence of messages exchanged between the user and the agent.
-Consider the following examples:
-
-- A chat session in ChatGPT.
-- A delegation of task to a workflow agent from a user, with data exchanged between the user
-    and the workflow such as occassional feedbacks from the user and status updates from the workflow.
-
-A user session may involve multiple runs.
-
-
-## User session state
-
-Rather than classifying agents as stateless or stateful, we focus on how state is managed during a user session.
-
-There are several states that an application may maintain during a user session:
-- **Conversation or workflow state**. This is the conversation history or execution 
-    history in a workflow. This state is typically owned and managed by the thread object.
-- **Long-term memory**. This can be information relevant to the user, 
-    such as user preferences, past interactions, or other relevant data.
-    This can also be information relevant to the task, such as past trajectories,
-    past results, or other task-related data. These states are typically
-    owned and managed by a memory object.
-
-The thread is always passed through the agent's `run` method.
-Memory may be attached to the thread or passed to the agent's constructor.
-
-See the [Context Providers](context_providers.md) design document for more details on how memory
-and other context providers like RAG are used in the framework.
-
-It is up to the application to decide whether to reuse state across different
-user sessions. The framework should provide the necessary methods and storage layer integration
-for persisting and retrieving state, but the application should decide how to use them.
-
-## Run agent concurrently
-
-If the agent just call models and tools that are stateless, 
-we can run the same instance of the agent concurrently.
-
-```python
-# Create threads for concurrent tasks.
-thread1 = ChatMessageThread.create()
-thread2 = ChatMessageThread.create()
-
-# Run the agent concurrently on multiple threads.
-results = await asyncio.gather(
-    agent.run([Message(...)], thread1, context),
-    agent.run([Message(...)], thread2, context),
-)
-# The `context`'s event handlers will emit events from both runs.
-```
-
-This is not always the right way to run concurrent agents, as some tools
-or memory associated with the agent may not be concurrent-safe.
-
-It is up the application to decide if an agent can run concurrently,
-or multiple instances should be created for each thread.
-
-
-## Using Foundry Agent Service
-
-The framework offers a built-in agent class for users of the Foundry Agent Service.
-The agent class essentially acts as a proxy to the agent hosted by the Foundry Agent Service.
-
-```python
-agent = FoundryAgent(
-    name="my_foundry_agent",
-    project_client="ProjectClient",
-    agent_id="my_agent_id", # If not provided, a new agent will be created.
-    deployment_name="my_deployment",
-    instruction="my_instruction",
-    ... # Other parameters for the agent creation.
-)
-
-# Create a thread that is backed by the Foundry Agent Service.
-thread = FoundryThread(thread_id="my_thread_id")
-
-# Run the agent on the thread and an new context that emits events to the console.
-result = await agent.run([Message(...)], thread, RunRunContext(event_channel="console"))
-```
-
-## Alternative agent abstractions
-
-There are two alternatives:
-
-1. **Agent with private conversation state**: The agent manages its own conversation state,
-    either by using a thread or other custom logics. The conversation state is 
-    not shared with other agents or workflows. It is up to the agent to decide how
-    to manage the conversation state.
-2. **Agent without conversation state**: The conversation state is externalized
-    and managed by a thread abstraction. The agent is invoked with a thread on
-    every run. While it can still use the thread to append messages etc., it loses
-    control over the conversation state the moment the run method returns.
-
-### Protocol comparison
-
-For agent with private conversation state, agent is invoked with new messages
-and the agent is responsible for managing the conversation state while exposing
-public methods for the orchestration code to manipulate its conversation state
-indirectly.
-
-```python
-class Agent(ABC):
-
-    async def run(
-        self, 
-        messages: list[Message],
-        context: RunContext,
-    ) -> Result:
-        """The method to run the agent and return the result.
-
-        Args:
-            messages: The list of new messages to process.
-            context: The context for the current invocation of the agent, providing
-                access to the event channel, and human-in-the-loop (HITL) features.
-
-        Returns:
-            The result of running the agent, which includes the final response.
-        """
-        ...
-    
-    async def reset() -> None:
-        """Reset the conversation state of the agent."""
-        ...
-    
-    # And other methods for managing the conversation state.
-```
-
-For agent without conversation state, the agent is invoked with a thread
-and the agent is responsible for processing the messages in the thread.
-
-```python
-class Agent(ABC, Generic[TThread]):
-
-    async def run(
-        self, 
-        messages: list[Message],
-        thread: TThread,
-        context: RunContext,
-    ) -> Result:
-        """The method to run the agent on a thread of messages, and return the result.
-
-        Args:
-            messages: The list of new messages to process.
-            thread: The current conversation state.
-            context: The context for the current invocation of the agent, providing
-                access to the event channel, and human-in-the-loop (HITL) features.
-        Returns:
-            The result of running the agent, which includes the final response.
-        """
-        ...
-```
-
-### Constructor comparison
-
-For agent with private conversation state, the agent is initialized with
-the a state in addition to components like model client and tools, which could be a thread passed to the constructor,
-or a custom state object that the agent uses to manage its conversation state.
-
-```python
-class CustomAgent(Agent[ChatMessageThread]):
-    def __init__(self, 
-        model_client: ModelClient,
-        tools: list[Tool],
-        state: CustomState, # Could be a thread or a custom state object, or nothing at all.
-    ) -> None:
-        self.model_client = model_client
-        self.tools = tools
-        self.state = state # Could be created by the agent within the constructor.
-
-```
-
-For agent without conversation state, the agent is initialized with
-the components it needs to process messages, such as a model client and tools.
-
-```python
-class CustomAgent(Agent[ChatMessageThread]):
-    def __init__(
-        self, 
-        model_client: ModelClient,
-        tools: list[Tool],
-    ) -> None:
-        self.model_client = model_client
-        self.tools = tools
-```
-
-### Thread-Agent compatibility considerations
-
-For agent with private conversation state, compatibility with thread is not a concern,
-as this is completely managed by the agent itself.
-
-For agent without conversation state, the thread must be compatible with the agent's
-`run` method. For example, a `FoundryAgent` must work with a `FoundryThread`
-because the thread is backed by the Foundry Agent Service, and the implementation
-requires the thread to be compatible with the service's API.
-
-Compatibility constraints:
-- `FoundryAgent` must work with `FoundryThread`.
-- `OpenAIAssistantAgent` must work with `OpenAIAssistantThread`.
-- `ResponsesAgent` must work with `ResponsesThread`, when using the stateful mode of the Responses API.
-
-### Workflow-Agent compatibility considerations
-
-For agent with private conversation state, the orchestration code cannot directly
-modifies the conversation state of every agent in the workflow.
-This means that for resetting the conversation state, branching a conversation,
-or other orchestration logic, the agent must provides public
-methods for the orchestration code to manipulate its conversation state.
-
-Potential methods (just initial ideas):
-- `reset()` to reset the conversation state.
-- `branch()` to create a new branch of the conversation state from an existing state.
-
-Example: AutoGen's MagenticOne orchestration requires the agents to be able to
-reset their conversation states during re-planning. It is reasonable to expect
-other types of orchestration logic will require behavior like branching
-or backtracking.
-
-For agent without conversation state, the orchestration code can directly
-manipulate the thread that is passed to the agent's `run` method. So the orchestration code
-can clone, fork, or reset the thread as needed.
-This also means that the agent's converstion state must be abstracted as a thread.
-
-### Extensibility considerations
-
-For agent with private conversation state, the management of the conversation state
-is completely up to the agent implementation. This means that custom agents can
-be created with different conversation state management strategies, such as:
-- Using a custom thread implementation that provides additional features.
-- Using a custom state object that provides additional features.
-When using a custom state object, the developer must also implement
-methods for exporting and importing the state.
-
-For agent without conversation state, the thread abstraction is required to
-encapsulate the conversation state and ensure that the agent's `run` method
-can use it without any issues. This puts a constraint on the agent implementation,
-and also what can be represented as state in the thread.
-Though, if the thread abstraction is designed well, it relieves the developer
-from implementing the conversation state management logic themselves.
-The developer only needs to come up with custom thread when the built-in thread
-abstraction does not work with their custom agent.
-
-### Discussion
-
-- Either agent or thread must manage the conversation state.
-- The class that manages the conversation state must provide a way to manipulate
-    it for orchestration purposes.
-- Isolate thread as a separate required abstraction may introduce compatibility
-    issues.
-- A thread abstraction with methods for manipulating the conversation state
-    should always be provided by the framework, whether it is exposed again
-    through the agent or not.
-
-In a scenario with built-in agents and built-in threads, the developer experience
-is nearly identical except for agent without conversation state the developer
-must ensure the thread is compatible with the agent's `run` method.
-
-In a scenario with custom agents and built-in threads, the developer experience
-is simpler for agent without conversation state, as the thread abstraction
-is already provided by the framework and the agent can use it directly. Plus,
-the developer doesn't need to implement the conversation state management logic
-through the agent's other methods, which will mostly likely be boilerplate code.
-
-In a scenario with built-in agents and custom threads, the developer experience
-is nearly identical, as in either case the developer must ensure
-the agent's `run` method is compatible with the thread or general state object.
-
-In a scenario with custom agents and custom threads, the developer experience
-is nearly identical, as in either case the developer must ensure
-the agent's `run` method is compatible with the thread or general state object,
-and that the state management logic is implemented in the agent or the thread.
-
-| Scenario | Agent with Conversation State | Agent without Conversation State |
-|----------|------------------------------------------|---------------------------------------------|
-| Built-in Agents, Built-in Threads | Simpler -- it should just work as there is no compatibility issue at runtime | Developer must ensure thread compatibility with agent's `run` method at runtime |
-| Custom Agents, Built-in Threads | Developer must implement state management methods on the agent. | Simpler, as thread abstraction is provided by the framework and agent can use it directly |
-| Built-in Agents, Custom Threads | Developer must ensure compatibility of the custom thread or state with agent's `run` method | Developer must ensure compatibility of the custom thread with agent's `run` method |
-| Custom Agents, Custom Threads | Developer is fully responsible for implementing state management. | Developer is fully responsible for implementing state management. |
-
-Overall, the agent without conversation state abstraction
-provides a simpler and more consistent developer experience, as it relies on
-the thread abstraction provided by the framework. The downside is that 
-developer must ensure the thread used is compatible with the agent's `run` method
--- this can be mitigated by enforcing strong types and validation, as well as
-built-in factory methods for creating new threads given the agent type.
-
-Another factor to consider is that Semantic Kernel already has agent abstraction
-that passes a thread per invocation, so it is easier for us to migrate to the
-new interface. 
-
-**Decision**: We will use the agent abstraction without conversation state 
-as the interface for agents in the framework.
-
-> **We should continue to question this decision as we implement more agents and workflows, and revisit the design.**

docs/design/context_providers.md

@@ -1,75 +0,0 @@
-# Memory, RAG, and other Context Providers
-
-Prior to calling a model client, it's often necessary to add information to the client's context window gathered from various sources.
-Two prime examples are long-term memory and retrieval-augmented generation (RAG) systems.
-The ContextProvider class supports such scenarios through a unified interface for storing and retrieving context data.
-
-## `ContextProvider` base class
-
-```python
-class ContextProvider(ABC):
-    """
-    The base class for context providers like Memory and RAG.
-    Subclasses will typically have extra methods and constructor parameters for specific functionality,
-    such as clearing memory contents, or adding files to a RAG provider. 
-    """
-
-    @abstractmethod
-    async def get_relevant_context(self, messages: list["Message"]) -> ProvidedContext | None:
-        """Searches for and returns any information relevant to the messages."""
-        ...
-
-    @abstractmethod
-    async def on_new_messages(self, messages: list["Message"]) -> None:
-        """Stores any information derived from the messages that may be useful to retrieve later."""
-        ...
-
-    # To close, delete and release any runtime resources, each subclass should override the built-in Python `del` method.    
-```
-
-## Usage
-
-As an example, consider the following scenario involving long-term memory as a context provider.
-
-Suppose that an app defines a subclass of `ContextProvider` called `Mem0Wrapper` which implements all required methods.
-At runtime the app instantiates the memory provider, passing any necessary parameters to its constructor.
-```python
-mem = Mem0Wrapper(<params>)
-```
-
-In this example, the app then clears memory to ensure that it starts empty.
-```python
-mem.clear()
-```
-
-Then the app creates an agent and passes the memory provider to it through the constructor or some other method.
-```python
-agent.add_context_provider(mem)
-```
-
-After creating the agent, the app calls `agent.run(message, thread, run_config)` as usual,
-where the user message assigns a task that requires knowledge the agent doesn't have.
-`agent.run()` calls `get_relevant_context(message)` on each of the agent's context providers,
-but `None` is returned since memory is empty.
-Then `agent.run()` calls the model client as usual, but the LLM can't solve the task.
-It may realize the information is missing, and ask the user for it.
-
-The original user message (which assigned the task) is then added to the thread's message history as usual,
-which automatically calls the `Agent.on_new_messages(messages)`,
-which calls `on_new_messages` on each context provider.
-In this case the memory provider fails to find any useful information in the user's message to store.
-
-Suppose then that the user responds by supplying the missing information.
-This time the agent will succeed, since the LLM's context window now contains the relevant information.
-More importantly for our example, when the second user message is added to the thread's message history,
-`mem.on_new_messages()` will extract and store the relevant information for later retrieval.
-
-For this example, suppose the user then initiates a new chat (clearing the message history),
-and assigns the original task again, but without providing the missing information.
-This time when `mem.get_relevant_context(message)` is called, the memory provider finds the relevant information stored from the previous chat.
-Then `agent.run()` attaches the retrieved information to the context window before calling the model client,
-which allows the agent to succeed at the task without the user needing to repeat the missing information.
-
-For more advanced memory implementations that have the ability to learn from their own experience
-(instead of only from the user), `mem.get_relevant_context(message)` may return useful context
-that was not previously extracted by `mem.on_new_messages(messages)`.

docs/design/evaluation.md

@@ -1,129 +0,0 @@
-## Evaluation
-
-The goal of Evaluation is to enable developers measure both the quality of agent responses and the efficiency of their decision-making processes.
-
-### Core Evaluation Concepts
-
-To enable effective evaluation (mindful of the fact that agents may be implemented with different approaches or even frameworks), it is useful to focus on the following core concepts:
-
-- **Standardized Trajectory Format**: A unified representation of agent interactions (messages, tool calls, events) enabling consistent evaluation across different agent implementations.
-- **Trajectory and Outcome Evaluation**: Analyze both the path an agent takes and the final response it generates. This includes evaluating the sequence of tool calls, the order of operations, and the final output.
-
-### Evaluation Components
-
-The framework provides these key evaluation components:
-
-- **Trajectory Converter**: Transforms agent runs from various frameworks into a standardized format for evaluation.
-- **Metrics Library**:
-  - Computation-based metrics: Direct algorithms that calculate objective measures without requiring a model
-  - Model-based metrics: Evaluation criteria that require an AI model to assess subjective qualities
-- **Judge**: For model-based metrics, a judge is the LLM responsible for applying evaluation criteria. Different judge models can be selected based on evaluation needs.
-- **Evaluator**: Coordinates the evaluation process by running computation-based metrics directly and applying judges to model-based metrics.
-- **Integration**: Connect with cloud evaluation services including Azure AI Evaluation.
-
-### (Example) Metrics
-
-Metrics may be pointwise (evaluating a single response on some criteria) or pairwise (evaluating two responses against each other e.g., where some ground truth is available).
-
-#### Computation-based Metrics
-
-- **Tool Match**: Measures tool call sequence matching in various ways:
-  - Exact Match: Perfect match with reference sequence
-  - In-Order Match: Required tools called in correct order (extra steps allowed)
-  - Any-Order Match: All required tools called regardless of order
-- **Precision**: Proportion of agent's tool calls that match reference tool calls.
-- **Recall**: Proportion of reference tool calls included in the agent's tool calls.
-- **Single Tool Usage**: Checks if a specific tool was used during the trajectory.
-- **Tool Call Errors**: Measures rate of tool call failures or errors.
-- **Latency**: Time required for agent to complete its task.
-
-#### Model-based Metrics
-
-- **Task Adherence**: Evaluates how well the agent's response addresses the assigned task.
-- **Coherence**: Assesses logical flow and internal consistency of the response.
-- **Safety**: Detects potential harmful content in responses.
-- **Follows Trajectory**: Evaluates if the response logically follows from the tools used.
-- **Efficiency**: Measures if the agent took an optimal path to reach the solution.
-
-This can build on the suite of metrics provided by [Azure AI evaluation](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/develop/agent-evaluate-sdk).
-
-### Sample Developer Experience
-
-**Sample Developer Experience:**
-
-1. **Run Agent**: Execute your agent on tasks to generate trajectories.
-2. **Create Trajectory**: Structure task, run data, and optional reference.
-3. **Configure Metrics**: Select pre-built or custom metrics for evaluation.
-4. **Evaluate**: Run evaluator to get scores and detailed results.
-5. **Analyze**: Review metrics to identify improvements.
-
-```python
-from azure.ai.evaluation import AzureOpenAIModelConfiguration
-from agent_framework.evaluation import (
-    TrajectoryMatchMetric,
-    TaskAdherenceMetric,
-    Evaluator,
-    Trajectory
-)
-
-# Model configuration for judge
-model_config = AzureOpenAIModelConfiguration(
-    azure_deployment="o3-mini",
-    api_version="2024-02-01",
-    temperature=0
-)
-
-# Run your agent
-task = "What's the weather in Seattle?"
-run = your_agent.run(task)
-
-# Create trajectory object
-trajectory = Trajectory(
-    task=task,
-    run=run,
-    reference=[  # Optional reference trajectory
-        {"type": "tool_call", "tool": "weather_api", "args": {"location": "Seattle"}},
-        {"type": "response", "content": "Weather information for Seattle"}
-    ]
-)
-
-# Define metrics
-trajectory_match = TrajectoryMatchMetric(match_type="exact")
-task_adherence = TaskAdherenceMetric(
-    criteria={
-        "Task adherence": (
-            "Does the response address the user's request and incorporate "
-            "information from tool calls appropriately?"
-        )
-    },
-    rating_rubric={
-        "5": "Excellent - Fully addresses task with complete detail",
-        "4": "Good - Addresses most aspects effectively",
-        "3": "Adequate - Addresses core task, minor gaps",
-        "2": "Poor - Partial addressing with significant gaps",
-        "1": "Inadequate - Fails to address task properly"
-    }
-)
-
-# Create evaluator
-evaluator = Evaluator(
-    metrics=[trajectory_match, task_adherence],
-    model_config=model_config,
-    trajectory=trajectory
-)
-
-# Run evaluation
-result = evaluator.run()
-
-# Results follow Azure format
-print("Evaluation Results:")
-for metric_name, score in result.items():
-    if isinstance(score, dict):
-        print(f"{metric_name}: {score.get('score', 'N/A')}")
-        print(f"  Result: {score.get('result', 'N/A')}")
-        print(f"  Reason: {score.get('reason', 'N/A')}")
-    else:
-        print(f"{metric_name}: {score}")
-
-
-```

docs/design/guardrails.md

@@ -1,50 +0,0 @@
-# Guardrails
-
-The design goal is to provide a flexible and extensible way to implement guardrails
-and a built-in set of guardrails that can be used for common use cases.
-
-> NOTE: this is work in progress.
-
-Guardrails can be template-based to adapt to different input data types, which
-include:
-- `Message` for agent messages.
-- `ToolCall` for tool call requests.
-- `ToolResult` for tool call results.
-
-Guardrails are added to other components such as `ModelClient` and `MCPServer`
-as hooks that are called before and after the main logic of the component.
-
-For example, the `ModelClient` has methods to add input and output guardrails.
-
-```python
-model_client = ModelClient(...)
-model_client.add_input_guardrails([
-    PIIGuardrail[Message](...),
-    SensitiveDataGuardrail[Message](...),
-])
-model_client.add_output_guardrails([
-    HarmfulContentGuardrail[Message](...),
-])
-```
-
-Another example to show how to use a guardrail with an MCP server:
-
-```python
-guardrail = PIIGuardrail(
-    config={
-        "rules": [
-            {
-                "type": "email",
-                "action": "block"
-            },
-            {
-                "type": "phone",
-                "action": "block"
-            }
-        ]
-    }
-)
-
-mcp_server = MCPServer(...)
-mcp_server.add_output_guardrail(guardrail)
-```

docs/design/mcp-servers.md

@@ -1,71 +0,0 @@
-# MCP Servers
-
-An MCP server is a component that wraps a session to an
-[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server.
-
-The tools provided by MCP server should match the tool interface to ensure
-minimal boilerplate code when dealing with both tools and MCP servers.
-
-Other features like sampling and resources, should be accessible through
-the MCP server interface as well.
-
-
-## MCP Server base class (draft)
-
-```python
-
-class MCPServer(ABC):
-    """The base class for all MCP servers in the framework."""
-
-    @abstractmethod
-    async def list_tools(self, context: Context) -> list[ToolSchema]:
-        """List all available tools in the MCP server.
-
-        Returns:
-            A list of tool schemas available in the MCP server.
-        """
-        ...
-
-    @abstractmethod
-    async def call_tool(
-        self,
-        call: ToolCall,
-        context: Context,
-    ) -> ToolResult:
-        """Call a tool with the given name and arguments.
-
-        Args:
-            tool_name: The name of the tool to call.
-            args: The arguments to pass to the tool.
-            context: The context for the current invocation of the MCP server.
-
-        Returns:
-            The result of calling the tool.
-        """
-        ...
-    
-    def add_input_guardrails(
-        self, 
-        guardrails: list[InputGuardrail[ToolCall]]
-    ) -> None:
-        """Add input guardrails to the MCP server.
-
-        Args:
-            guardrails: The list of input guardrails to add.
-        """
-        ...
-    
-    def add_output_guardrails(
-        self, 
-        guardrails: list[OutputGuardrail[ToolResult]]
-    ) -> None:
-        """Add output guardrails to the MCP server.
-
-        Args:
-            guardrails: The list of output guardrails to add.
-        """
-        ...
-    
-```
-
-MCP specs have other APIs. We should consider adding them as well.

docs/design/models.md

@@ -1,305 +0,0 @@
-# Model Clients
-
-A model client is a component that implements a unified interface for
-interacting with different language models. It exposes a standardized metadata
-about the model it provides (e.g., model name, tool call and vision capabilities, etc.)
-to support validation and composition with other components.
-
-The framework provides a set of pre-built model clients:
-
-- `OpenAIChatCompletionClient`
-- `AzureOpenAIChatCompletionClient`
-- `AzureOpenAIResponseClient`
-- `AzureAIClient`
-- `AnthropicClient`
-- `GeminiClient`
-- `HuggingFaceClient`
-- `OllamaClient`
-- `VLLMClient`
-- `ONNXRuntimeClient`
-- `BedrockClient`
-- `NIMClient`
-
-Prompt template is a component that is used by model clients to generate prompts
-with parameters set based on some injected context.
-This gets into the actual interface and implementation detail of model clients,
-so we just mention it here.
-
-The design goal is to provide integration with a wide range of model providers,
-including both open-source and commercial models, while maintaining a consistent
-interface for developers to use.
-
-## `ModelClient` Protocol (draft)
-
-```python
-class ModelClient(Protocol):
-    """A protocol for a model client that can generate chat responses."""
-    async def generate_response(
-        self,
-        messages: Sequence[ChatMessage],
-        **options,  # kwargs?
-    ) -> ChatResponse:
-        """Sends chat messages and returns the response.
-
-        Args:
-            messages: The sequence of chat messages to send.
-            **options: Additional options for the chat request, such as model_id, temperature, etc.
-                       See `ChatOptions` for more details.
-
-        Returns:
-            The response messages generated by the client.
-
-        Raises:
-            ValueError: If the input message sequence is `None`.
-        """
-        ...
-
-    async def generate_streaming_response(
-        self,
-        messages: Sequence[ChatMessage],
-        **options,  # kwargs?
-    ) -> AsyncIterable[ChatResponseUpdate]:
-        """Sends chat messages and streams the response.
-
-        Args:
-            messages: The sequence of chat messages to send.
-            **options: Additional options for the chat request, such as model_id, temperature, etc.
-                       See `ChatOptions` for more details.
-
-        Returns:
-            An async iterable of chat response updates containing the content of the response messages
-            generated by the client.
-
-        Raises:
-            ValueError: If the input message sequence is `None`.
-        """
-        ...
-
-    def add_input_guardrails(
-        self,
-        guardrails: list[InputGuardrail[ChatMessage]]
-    ) -> None:
-        """Add input guardrails to the model client.
-
-        Args:
-            guardrails: The list of input guardrails to add.
-        """
-        ...
-
-    def add_output_guardrails(
-        self,
-        guardrails: list[OutputGuardrail[ChatResponse | Sequence[ChatResponseUpdate]]]
-    ) -> None:
-        """Add output guardrails to the model client.
-
-        Args:
-            guardrails: The list of output guardrails to add.
-        """
-        ...
-```
-
-## `ChatMessage`/ and `ChatResponse`/`StructuredChatResponse`/`ChatResponseUpdate` Types
-
-For the data types used to represent message and response contents, see `docs/design/types.md`.
-
-```python
-
-class ChatMessage(BaseModel):
-    author_name: str | None  # The name of the author of the message
-    contents: list[AIContent]  # The contents of the message, which can include text, images, function calls, etc.
-    message_id: str | None  # The ID of the message
-    raw_representation: Any | None = None  # The raw representation of the chat message from an underlying implementation
-    role: ChatRole  # The role of the author of the message
-    additional_properties: dict[str, Any] | None = None
-
-
-class ChatRole(BaseModel):
-    """Describes the intended purpose of a message within a chat interaction."""
-    value: str
-
-    SYSTEM: ClassVar[Self]  # The role that instructs or sets the behaviour of the AI system.
-    USER: ClassVar[Self]  # The role that provides user input for chat interactions.
-    ASSISTANT: ClassVar[Self]  # The role that provides responses to system-instructed, user-prompted input.
-    TOOL: ClassVar[Self]  # The role that provides additional information and references in response to tool use requests.
-```
-
-`ChatRole` is an enum-like class that defines the roles of the author in a chat message. We use a class with class variables to reduce the coupling between versions of the framework and the capabilities available in the various providers. This allows us to work with providers that support extra roles without having to change the framework code. (See also `ChatFinishReason`.)
-
-The response types are designed to support both structured and unstructured responses, allowing for streaming in the unstructured case.
-
-```python
-class ChatResponse(BaseModel):
-    """Represents the response to a chat request."""
-    messages: list[ChatMessage]  # The chat response messages.
-
-    additional_properties: dict[str, Any] | None = None  # Any additional properties associated with the chat response.
-    conversation_id: str | None = None  # An identifier for the state of the conversation.
-    created_at: CreatedAtT | None = None  # A timestamp for the chat response. (TODO: Use a datetime type?)
-    finish_reason: ChatFinishReason | None = None  # The reason for the chat response.
-    model_id: str | None = None  #The model ID used in the creation of the chat response.
-    raw_representation: Any | None = None  # The raw representation of the chat response from an underlying implementation.
-    response_id: str | None = None  # The ID of the chat response.
-    usage_details: UsageDetails | None = None  # The usage details for the chat response.
-
-
-TValue = TypeVar("TValue", bound=pydantic.BaseModel)  # The value type needs to be deserializable (so we rely on Pydantic)
-
-
-class StructuredResponse(GenericModel, Generic[TValue], ChatResponse):
-    """Represents a structured response to a chat request."""
-    value: TValue
-
-
-class ChatFinishReason(BaseModel):
-    """Represents the reason a chat response completed."""
-    value: str
-
-    CONTENT_FILTER: ClassVar[Self]  # type: ignore[assignment]
-    """A ChatFinishReason representing the model filtering content, whether for safety, prohibited content,
-    sensitive content, or other such issues."""
-    LENGTH: ClassVar[Self]  # type: ignore[assignment]
-    """A ChatFinishReason representing the model reaching the maximum length allowed for the request and/or
-    response (typically in terms of tokens)."""
-    STOP: ClassVar[Self]  # type: ignore[assignment]
-    """A ChatFinishReason representing the model encountering a natural stop point or provided stop sequence."""
-    TOOL_CALLS: ClassVar[Self]  # type: ignore[assignment]
-    """A ChatFinishReason representing the model requesting the use of a tool that was defined in the request."""
-```
-
-For ease of use, all of `ChatMessage`, `ChatResponse`, `StructuredResponse` (and `ChatResponseUpdate`) provide a helper method to extract the text content. Note that all it does is concatenate any `TextContent` instances found in the contents. It will ignore any other content types, including `TextReasoningContent`.
-
-```python
-    @property
-    def text(self) -> str:
-        """Returns the concatenated text of all messages in the response."""
-    return " ".join(content.text for content in self.contents if isinstance(content, TextContent))
-```
-
-The streaming response type is designed to represent a "differential" of a full response object, in that the relationship between the two is akin to: `Join(ChatResponseUpdate) === ChatResponse`.
-
-```python
-class ChatResponseUpdate(BaseModel):
-    """Represents a single streaming response chunk from a `ModelClient`."""
-    contents: list[AIContent]
-    """The chat response update content items."""
-
-    additional_properties: dict[str, Any] | None = None
-    """Any additional properties associated with the chat response update."""
-    author_name: str | None = None
-    """The name of the author of the response update."""
-    conversation_id: str | None = None
-    """An identifier for the state of the conversation of which this update is a part."""
-    created_at: CreatedAtT | None = None  # use a datetimeoffset type?
-    """A timestamp for the chat response update."""
-    finish_reason: ChatFinishReason | None = None
-    """The finish reason for the operation."""
-    message_id: str | None = None
-    """The ID of the message of which this update is a part."""
-    model_id: str | None = None
-    """The model ID associated with this response update."""
-    raw_representation: Any | None = None
-    """The raw representation of the chat response update from an underlying implementation."""
-    response_id: str | None = None
-    """The ID of the response of which this update is a part."""
-    role: ChatRole | None = None
-    """The role of the author of the response update."""
-```
-
-`StreamingResponseUpdate` provides helpers to join a set of updates into a single `ChatResponse` object, as well as to create the next update in a stream given the content of the new update.
-
-## `ModelOptions`: Configuring a Model Client request
-
-Although the `ModelClient` protocol uses named arguments to pass options to the `generate_response` and `generate_streaming_response` methods, we also provide a `ModelOptions` class representing the total set of configurable options that the user could reasonably expect on a `ModelClient` implementation. It also provides a convenient way to document them in one place.
-
-```python
-
-class ChatOptions(TypedDict, total=False):
-    """Represents the options for a chat request.
-
-    Remarks:
-        This class is here for the purposes of documentation and ease of use. Options should still
-        be passed as keyword arguments to the `ModelClient.generate_response` and
-        `ModelClient.generate_streaming_response` methods.
-    """
-    allow_multiple_tool_calls: bool | None = None
-    """Indicates whether a single response is allowed to include multiple tool calls. If `False`,
-    the `ModelClient` is asked to return a maximum of one tool call per request. If `True`, there is
-    no limit. If `None`, the provider may select its own default."""
-    conversation_id: str | None = None
-    """An optional identifier used to associate a request with an existing conversation."""
-    frequency_penalty: float | None = None
-    """A penalty for repeated tokens in chat responses proportional to how many times they've appeared."""
-    max_output_tokens: int | None = None
-    """The maximum number of tokens in the generated chat response."""
-    model_id: str | None = None
-    """The model ID for the chat request."""
-    presence_penalty: float | None = None
-    """a value that influences the probability of generated tokens appearing based on their existing
-    presence in generated text."""
-    response_format: ChatResponseFormat | None = None
-    """The response format for the chat request."""
-    seed: int | None = None
-    """A seed value used by a service to control the reproducibility of results."""
-    stop_sequences: list[str] | None = None
-    """The list of stop sequences."""
-    temperature: float | None = None
-    """The temperature for generating chat responses."""
-    tool_mode: ChatToolMode | None = None
-    """The tool mode for the chat request."""
-    tools: list[AITool] | None = None
-    """The list of tools to include with a chat request."""
-    top_k: int | None = None
-    """The number of most probable tokens that the model considers when generating the next part of
-    the text."""
-    top_p: float | None = None
-    """The 'nucleus sampling' factor (or "top p") for generating chat responses."""
-```
-
-`ChatResponseFormat` and `ChatToolMode` are used to configure the output format (structured or not) and tool use mode.
-
-```python
-
-class ChatResponseFormatJson(BaseModel):
-    """Represents a response format for structured JSON data."""
-    type: Literal["json"] = "json"
-
-    schema_name: str | None = None
-    """The name of the schema."""
-    schema_description: str | None = None
-    """The description of the schema."""
-    schema_: dict[str, Any] | None = Field(default=None, alias="schema")
-    """The JSON schema associated with the response, or `None` if there is none."""
-
-
-class ChatResponseFormatText(BaseModel):
-    """Represents a response format with no constraints around the format."""
-    type: Literal["text"] = "text"
-
-
-ChatResponseFormat = ChatResponseFormatJson | ChatResponseFormatText
-
-
-class AutoChatToolMode(BaseModel):
-    """Indicates that a `ModelClient` is free to select any of the available tools, or none at all."""
-    value: Literal["auto"] = "auto"
-
-
-class NoneChatToolMode(BaseModel):
-    """Indicates that a `ModelClient` should not request the invocation of any tools."""
-    value: Literal["none"] = "none"
-
-
-class RequiredChatToolMode(BaseModel):
-    """Represents a mode where a chat tool must be called.
-
-    This class can optionally nominate a specific function or indicate that any of the functions can be
-    selected.
-    """
-    value: Literal["require_any", "require_specific"] = "require_any"
-
-    required_function_name: str | None = None
-    """The name of a specific function that must be called."""
-
-
-ChatToolMode = AutoChatToolMode | NoneChatToolMode | RequiredChatToolMode
-```

docs/design/observability.md

@@ -1,3 +0,0 @@
-# Observability and Monitoring
-
-Traces should follow the [OTEL GenAI Conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/).

docs/design/optimization.md

@@ -1,10 +0,0 @@
-# Optimization and Tuning
-
-> For future consideration.
-
-The framework should support optimization of agents and workflows
-with task feedback, by tuning the various components such as 
-system prompts, model parameters, and tool configurations.
-
-We should also consider fine-tuning of the models and embeddings
-as part of the optimization process.

docs/design/python-package-setup.md

@@ -22,7 +22,7 @@
             "agent-framework-google == 1.0.0"
         ]
         ```
-    * this means developers can use `pip install agent-framework[google]` to get AF with all Google connectors and dependencies, as well as manually installing the subpackage with `pip install agent-framework-google`.
+    * this means developers can use `pip install agent-framework[google] --pre` to get AF with all Google connectors and dependencies, as well as manually installing the subpackage with `pip install agent-framework-google --pre`.
 
 ### Sample getting started code
 ```python
@@ -53,45 +53,46 @@ Overall the following structure is proposed:
     * core components, will be exposed directly from `agent_framework`:
         * (single) agents (includes threads)
         * tools (includes MCP and OpenAPI)
-        * models/types (name tbd, will include the equivalent of MEAI for dotnet; content types and client abstractions)
+        * types
+        * context_providers
         * logging
-    * advanced components, will be exposed from `agent_framework.<component>`:
-        * context_providers (tbd)
-        * guardrails / filters
-        * vector_data (vector stores and other MEVD pieces)
-        * text_search
-        * exceptions
-        * evaluations
-        * utils (optional)
-        * telemetry (could also be observability or monitoring)
         * workflows (includes multi-agent orchestration)
-    * connectors; subpackages
-        * Subpackages are any additional functionality that is useful for a user, to reduce friction they will imported in a similar way as advanced components, however the code for them will be in a separate package, so that they can be installed separately, they must expose all public items, in their main `__init__.py` file, so that they can be imported from the main package without additional import levels.
-        In the main package a corresponding folder will be created, with a `__init__.py` file that lazy imports the public items from the subpackage, so that they can be exposed from the main package.
-        * Some examples are:
-            * azure (non LLM integrations)
-            * will be exposed through i.e. `agent_framework.azure`
-            * anything other then a connector that we want to expose as a separate package, for instance:
-                * mem0 (memory management)
-                * would be exposed through i.e. `agent_framework.mem0`
-        * A package name cannot overlap with each other or with components in the main package, so `guardrails` cannot be used as a package name, since it is already used in the main package.
-            * A package can implement additional guardrails functionality, but that would become something like `from agent_framework.azure import ContentSafetyGuardrail`, which would contain a guardrail implementation using Azure Content Safety, but it is not the same as the `agent_framework.guardrails` component.
+        * middleware
+        * telemetry (user_agent)
+    * advanced components, will be exposed from `agent_framework.<component>`:
+        * vector_data (tbd, vector stores and other MEVD-like pieces)
+        * text_search (tbd)
+        * exceptions
+        * evaluations (tbd)
+        * utils (optional)
+        * observability
+    * vendor folders with connectors and integrations, will be exposed from `agent_framework.<vendor>`:
+        * Code can be both in folder or in subpackage with lazy import.
+        * See subpackage scope below for more detail
 * tests
 * samples
 * extensions
     * azure
     * ...
 
-All the init's will use lazy loading so avoid importing the entire package when importing a single component.
+All the init's in the subpackages will use lazy loading so avoid importing the entire package when importing a single component.
 Internal imports will be done using relative imports, so that the package can be used as a namespace package.
 
 ### File structure
-The resulting file structure will be as follows:
+The resulting file structure will be as follows (not all things currently implemented, just an example):
 
 ```plaintext
 packages/
     main/
         agent_framework/
+            azure/
+                __init__.py
+                _chat_client.py
+                ...
+            microsoft/
+                __init__.py
+                _copilot_studio.py
+                ...
             openai/
                 __init__.py
                 _chat_client.py
@@ -103,17 +104,16 @@ packages/
             _tools.py
             _models.py
             _logging.py
-            context_providers.py
-            guardrails.py
+            _middleware.py
+            _telemetry.py
+            observability.py
             exceptions.py
-            evaluations.py
             utils.py
-            telemetry.py
-            templates.py
-            text_search.py
-            vector_data.py
-            workflows.py
             py.typed
+        _workflow/
+            __init__.py
+            _workflow.py
+            ...etc...
         tests/
             unit/
                 test_types.py
@@ -122,28 +122,27 @@ packages/
         pyproject.toml
         README.md
         ...
-    mem0/
-        agent_framework/
-            mem0/
-                __init__.py
-                _mem0.py
-                ...
+    azure-ai-agents/
+        agent_framework-azure-ai-agents/
+            __init__.py
+            _chat_client.py
+            ...
+        tests/
+            test_azure_ai_agents.py
+        samples/ (optional)
+            ...
+        pyproject.toml
+        README.md
+        ...
     redis/
         ...
-    google/
-        agent_framework/
-            google/
-                __init__.py
-                _chat.py
-                _bigquery.py
-                ...
+    mem0/
+        agent_framework-mem0/
+            __init__.py
+            _provider.py
+            ...
         tests/
-            unit/
-                test_google_client.py
-                test_google_tools.py
-                ...
-            integration/
-                test_google_integration.py
+            test_mem0_provider.py
         samples/ (optional)
             ...
         pyproject.toml
@@ -163,79 +162,31 @@ We might add a template subpackage as well, to make it easy to setup, this could
 
 In the [`DEV_SETUP.md`](../../python/DEV_SETUP.md) we will add instructions for how to deal with the path depth issues, especially on Windows, where the maximum path length can be a problem.
 
+### Subpackage scope
+Sub-packages are comprised of two parts, the code itself and the dependencies, the choice of when to use a subpackage and when to use a extra in the main package is based on the status of dependencies and/or possibilities of a external support mechanism. What this means is that:
+
+- Integrations that need non-GA dependencies will be sub-packages and installed only when using a extra, so that we can avoid having non-GA dependencies in the main package.
+- Integrations where the AF-code is still experimental, preview or release candidate will be sub-packages, so that we can avoid having non-GA code in the main package and we can version those packages properly.
+- Integrations that are outside Microsoft and where we might not always be able to fast-follow breaking changes, will stay as sub-packages, to provide some isolation and to be able to version them properly.
+- Integrations that are mature and that have released (GA) dependencies and features on the service side will be moved into the main package, the dependencies of those packages will stay installable under the same `extra` name, so that users do not have to change anything, and we then remove the subpackage itself.
+- All subpackage imports in the code should be from a stable place, mostly vendor-based, so that when something moves from a subpackage to the main package, the import path does not change, so `from agent_framework.microsoft import CopilotAgent` will always work, even if it moves from the `agent-framework-microsoft-copilot` package to the main `agent-framework` package.
+- The imports in those vendor namespaces (these won't be actual python namespaces, just the folders with a __init__.py file and any code) will do lazy loading and raise a meaningful error if the subpackage or dependencies are not installed, so that users know which extra to install with ease.
+- On a case by case basis we can decide to create additional a `extra`, that combines multiple sub-packages and dependencies into one extra, so that users who work primarily with one platform can install everything they need with a single extra, for example (not implemented) you can install with the `agent-framework[azure-purview]` extra that only implement a `PurviewMiddleware`, or you can install with the `agent-framework[azure]` extra that includes all Azure related connectors, like `purview`, `content-safety` and others (all examples, not actual packages), regardless of where the code sits, these should always be importable from `agent_framework.azure`.
+- Subpackage naming should also follow this, so in principle a package name is `<vendor/folder>-<feature/brand>`, so `google-gemini`, `azure-purview`, `microsoft-copilotstudio`, etc. For smaller vendors, where it's less likely to have a multitude of connectors, we can skip the feature/brand part, so `mem0`, `redis`, etc.
+- For Microsoft services we will have two vendor folders, `azure` and `microsoft`, where `azure` contains all Azure services, while `microsoft` contains other Microsoft services, such as Copilot Studio Agents.
+
+This setup was discussed at length and the decision is captured in [ADR-0008](../decisions/0008-python-subpackages.md).
+
 #### Evolving the package structure
 For each of the advanced components, we have two reason why we may split them into a folder, with an `__init__.py` and optionally a `_files.py`:
 1. If the file becomes too large, we can split it into multiple `_files`, while still keeping the public interface in the `__init__.py` file, this is a non-breaking change
 2. If we want to partially or fully move that code into a separate package.
 In this case we do need to lazy load anything that was moved from the main package to the subpackage, so that existing code still works, and if the subpackage is not installed we can raise a meaningful error.
 
-> **Important**: This setup means that in a users machine, the code from the main package and the code from any installed subpackages will be put in the same folder in their python installation, this means there cannot be name clashes between the contents of a subpackage with each other, or with the main package. So the first level inside of those subpackages should be unique, preferably the same as the subpackage name. A subpackage can contain anything that is useful and related to Agent Framework, in that case for i.e. Azure, that would mean the following structure:
-
-```plaintext
-<!-- inside the Azure subpackage: -->
-agent_framework/
-    azure/
-        __init__.py
-        _chat.py
-        _embeddings.py
-        _context_safety.py
-        ...
-```
-
 ## Coding standards
 
 Coding standards will be maintained in the [`DEV_SETUP.md`](../../python/DEV_SETUP.md) file.
 
-[tool.ruff.lint]
-fixable = ["ALL"]
-unfixable = []
-select = [
-    "ASYNC", # async checks
-    "B", # bugbear checks
-    "CPY", #copyright
-    "D", #pydocstyle checks
-    "E", #error checks
-    "ERA", #remove connected out code
-    "F", #pyflakes checks
-    "FIX", #fixme checks
-    "I", #isort
-    "INP", #implicit namespace package
-    "ISC", #implicit string concat
-    "Q", # flake8-quotes checks
-    "RET", #flake8-return check
-    "RSE", #raise exception parantheses check
-    "RUF", # RUF specific rules
-    "SIM", #flake8-simplify check
-    "T100", # Debugger,
-    "TD", #todos
-    "W", # pycodestyle warning checks
-]
-ignore = [
-    "D100", #allow missing docstring in public module
-    "D104", #allow missing docstring in public package
-    "TD003", #allow missing link to todo issue
-    "FIX002" #allow todo
-]
-
-[tool.ruff.format]
-docstring-code-format = true
-
-[tool.ruff.lint.pydocstyle]
-convention = "google"
-
-[tool.ruff.lint.per-file-ignores]
-# Ignore all directories named `tests` and `samples`.
-"tests/**" = ["D", "INP", "TD", "ERA001", "RUF"]
-"samples/**" = ["D", "INP", "ERA001", "RUF"]
-# Ignore all files that end in `_test.py`.
-"*_test.py" = ["D"]
-"*.ipynb" = ["CPY", "E501"]
-
-[tool.ruff.lint.flake8-copyright]
-notice-rgx = "^# Copyright \\(c\\) Microsoft\\. All rights reserved\\."
-min-file-size = 1
-```
-
 ### Tooling
 uv and ruff are the main tools, for package management and code formatting/linting respectively.
 

docs/design/threads.md

@@ -1,124 +0,0 @@
-# Threads
-
-Threads are stateful objects to manage the conversation context of an agent or a workflow.
-They are meant to be shown to the user as part of a user interface.
-They can be persisted to a database or a file system, and used to
-resume a previous user session.
-
-Thread should use message and content types as defined in [Core Data Types](types.md).
-
-For workflows, a thread can contain sub-threads as a dictionary of threads. 
-This is to ensure agents in a workflow can run concurrently on different threads.
-The default thread has the key `main` and the sub-threads having keys that are usually
-corresponding to the agents in a workflow.
-
-For workflows, a thread should also support the concept of execution state, which includes:
-- The history of steps taken.
-- The current step in the workflow.
-- The next steps to be taken.
-This is to ensure the workflow can be resumed from where it left off, without losing
-the state of execution.
-
-The framework should provides default implementations of a thread class that:
-- Can be backed by a database (i.e., Redis) or a file system (i.e., JSON file).
-- Can be backed by the Foundry Agent Service.
-- Can be copied and forked.
-- Can be serialized and deserialized to/from JSON.
-- Can support checkpointing, rollback, and time travel, for both agent and workflow.
-- Can automantically export truncated views to be used by model clients to keep the context size within limits.
-
-## `AgentThread` base class
-
-```python
-class AgentThread(ABC):
-    """The base class for all threads defining the minimum interface."""
-
-    # ---------- Message-handling ----------
-    @abstractmethod
-    async def on_new_messages(self, messages: list["Message"]) -> None:
-        """Handle a new message added to the thread."""
-        ...
-
-    # ---------- Lifecycle management ----------
-    @classmethod
-    @abstractmethod
-    async def create(self) -> "AgentThread":
-        """Create a new thread of the same type."""
-        ...
-
-    # For delete and release resources, subclass should override built-in Python `del` method.    
-```
-
-## `ChatMessageThread` class
-
-The most common thread type is going to be the `ChatMessageThread`, which is a thread that stores the messages in a list. This thread type works well with `ChatCompletionAgent` and its subclasses.
-
-```python
-class ChatMessageThread(AgentThread):
-    """A thread that stores the messages in a list."""
-
-    def __init__(self):
-        # NOTE: We should have some way to prevent direct calling of the constructor from the base class
-        # and enforce using the `create` class method.
-        if ThreadCreationContext.is_active:
-            raise RuntimeError("Cannot instantiate ChatMessageThread directly. Use ChatMessageThread.create() instead.")
-        self._messages: list["Message"] = []
-    
-    @property
-    def messages(self) -> list["Message"]:
-        """Get the list of messages in the thread."""
-        return self._messages
-
-    async def on_new_messages(self, messages: list["Message"]) -> None:
-        """Handle a list of new messages added to the thread."""
-        self._messages.extend(messages)
-    
-    async def fork(self, message_id: str | None = None) -> "ChatMessageThread":
-        """Create a fork of the thread starting from the given message ID.
-
-        NOTE: we may need to create a new base class / protocol for this behavior.
-        
-        If no message ID is provided, the fork will start from the latest message."""
-        new_thread = ChatMessageThread()
-        if message_id is None:
-            new_thread._messages = self._messages.copy()
-        else:
-            index = next((i for i, msg in enumerate(self._messages) if msg.id == message_id), -1)
-            new_thread._messages = self._messages[index + 1:] if index != -1 else []
-        return new_thread
-
-    @classmethod
-    async def create(cls) -> "ChatMessageThread":
-        """Create a new chat history thread."""
-        with ThreadCreationContext.activate():
-            return cls()
-
-    async def delete(self) -> None:
-        """Delete the thread. It will not be recoverable."""
-        self._messages.clear()
-```
-
-## `WorkflowThread` class
-
-The `WorkflowThread` is a specialized thread that manages the execution state of a workflow. It extends the base `Thread` class and provides additional functionality to handle the workflow's execution steps and sub-threads.
-
-```python
-
-class WorkflowThread(AgentThread):
-    """A thread that manages the execution state of a workflow."""
-
-    # ----------- Execution state management -----------
-    # TBD
-
-    # ----------- Lifecycle management -----------
-    async def create_sub_thread(self, agent: Agent, key: str) -> "AgentThread":
-        """Create a sub-thread for the given agent with the given key."""
-        pass
-    
-    async def delete_sub_thread(self, key: str) -> None:
-        """Delete the sub-thread with the given key."""
-        pass
-    
-    async def get_sub_thread(self, key: str) -> "AgentThread":
-        """Get the sub-thread with the given key."""
-        pass

docs/design/tools.md

@@ -1,215 +0,0 @@
-# Tools
-
-> The design goal is to make it easy to create new tools and integrate existing APIs and make them available to agents.
-
-A tool is a component that can be used to invoke procedure code
-and returns a well-defined result type to the caller.
-
-The result type should indicate the success or failure of the invocation,
-as well as the output of the invocation in terms of the core data types.
-There may be other fields in the result type for things like
-side effects, etc.. We should address this when designing the
-tool interface.
-
-A tool may have arguments for invocation.
-The arguments must be defined using JSON schema that language model supports.
-
-A tool may have dependencies such as tokens, credentials,
-or output message channels that will be provided by through
-a context variable passed to the tool when it is invoked.
-
-A tool may also have guardrails that are used to ensure the
-tool is invoked with proper arguments, or that the agent has the
-right context such as human approval to invoke the tool.
-
-The framework provides a set of pre-built tools:
-
-- `FunctionTool`: a tool that wraps a function.
-- `AzureAISearchTool`: a tool that is backed by Azure AI Search Service.
-- `OpenAPITool`: a tool that is backed by a service that defines an OpenAPI spec.
-- Other tools backed by Foundry.
-
-## `Tool` base class
-
-```python
-@dataclass
-class ToolResult:
-    """The result of running a tool."""
-    is_error: bool
-    output: List[ImageContent | TextContent] # The content types are defined as part of the core data types.
-    ... # Other fields, could be extended to include more for application-specific needs.
-
-class Tool(ABC):
-    """The base class for all tools in the framework."""
-
-    @property
-    def name(self) -> str:
-        """The name of the tool, used to identify it in the system."""
-        ...
-    
-    @property
-    def description(self) -> str:
-        """The description of the tool, used to provide information about its
-        functionality.
-        """
-        ...
-
-    @property
-    def schema(self) -> ToolSchema:
-        """The schema of the tool, which defines the JSON schema of the input
-        arguments."""
-        ...
-
-    @property
-    def strict(self) -> bool:
-        """Whether the JSON schema is in strict mode. If true, no optional
-        arguments are allowed.
-        """
-        ...
-    
-    async def __call__(
-        self,
-        call: ToolCall,
-        context: Context,
-    ) -> ToolResult:
-        """The method to call to run the tool with arguments and return the result.
-        
-        Args:
-            call: The tool call containing the name and arguments to pass to the tool.
-            context: The context for the current invocation of the tool, providing
-                access to the event channel, and human-in-the-loop (HITL) features.
-
-        Returns:
-            The result of running the tool.
-        """
-        try:
-            # Call the on_invoke method to allow for input guardrails to be applied
-            # to the arguments before the tool is run.
-            await self.on_invoke(args, context)
-            # Call the run method to actually run the tool.
-            result = await self.run(args, context)
-            # Call the on_output method to handle the output of the tool.
-            result = await self.on_output(result, context)
-        except Exception as e:
-            # If an error occurs, call the on_error method to handle it.
-            result = await self.on_error(e, context)
-        return result
-
-    @abstractmethod
-    async def run(
-        self,
-        calls: ToolCall,
-        context: Context,
-    ) -> ToolResult:
-        """The method called by the tool itself to run the tool with arguments and return the result."""
-        ...
-    
-    async def on_invoke(
-        self,
-        calls: ToolCall,
-        context: Context,
-    ) -> None:
-        """The method called by the tool when is invoked but before it is run.
-
-        This is useful for input guardrails to be applied to the arguments
-        before the tool is run.
-        """ 
-        ...
-    
-    async def on_error(
-        self,
-        error: Exception,
-        context: Context,
-    ) -> ToolResult:
-        """The method called by the tool when an error is raised."""
-        ...
-    
-    async def on_output(
-        self,
-        output: ToolResult,
-        context: Context,
-    ) -> ToolResult:
-        """The method called by the tool when the output is ready.
-
-        This is where output guardrails can be applied to the result
-        before it is returned to the caller.
-        """
-        ...
-    
-    def add_input_guardrails(
-        self, 
-        guardrails: list[InputGuardrail[ToolCall]]
-    ) -> None:
-        """Add input guardrails to the tool.
-
-        Args:
-            guardrails: The list of input guardrails to add.
-        """
-        ...
-    
-    def add_output_guardrails(
-        self, 
-        guardrails: list[OutputGuardrail[ToolResult]]
-    ) -> None:
-        """Add output guardrails to the tool.
-
-        Args:
-            guardrails: The list of output guardrails to add.
-        """
-        ...
-    
-    def add_on_error_func(
-        self, 
-        on_error_func: Callable[[Exception, Context], Awaitable[ToolResult]]
-    ) -> None:
-        """Add a function to call when an error is raised during the call to `run`.
-
-        Args:
-            on_error_func: The function to call when an error is raised.
-        """
-        ...
-```
-
-## `FunctionTool`
-
-The `FunctionTool` is a decorator that can be used to create a tool from a function.
-
-```python
-@FunctionTool
-def web_search(
-    query: str,
-    num_results: int = 10,
-) -> str:
-    """A tool that performs a web search and returns the results."""
-    ...
-```
-
-`FunctionTool` supports customization of the following:
-- `name`
-- `description`
-- `on_error_func`: the function to call when an error is raised during the call to `run`.
-- `strict`: whether the JSON schema is in strict mode. If true, no optional
-  arguments are allowed.
-- `input_guardrails`: a list of input guardrails to apply to the arguments
-  before the tool is run.
-- `output_guardrails`: a list of output guardrails to apply to the result
-  before it is returned.
-
-## `AgentTool`
-
-The `AgentTool` is a wrapper around an agent that can be used as a tool.
-
-```python
-agent = SomeAgent(...)
-tool = AgentTool(
-    agent=agent,
-    name="SomeAgent",
-    description="Some description of this agent tool.",
-    output_extractor=..., # Optional, a function to extract a ToolResult from the agent's run Result.
-    on_error_func=..., # Optional, a function to call when an error is raised during the call to `run`.
-)
-```
-
-The argument to the `AgentTool` is a single string.
-
-> NOTE: Do we also need to support passing a thread to the agent tool?

docs/design/types.md

@@ -1,175 +0,0 @@
-# Core Data Types
-
-A design goal of the new framework to simplify the interaction between agent components
-through a common set of data types, minimizing boilerplate code
-in the application for transforming data between components.
-
-For example, text, images, function calls, tool schema are
-all examples of such data types.
-These data types are used to interact with agent components (model clients, tools, MCP, threads, and memory),
-forming the connective tissue between those components.
-
-In AutoGen, these are the data types mostly defined in `autogen_core.models` module,
-and others like `autogen_core.Image` and `autogen_core.FunctionCall`. This is just
-an example as AutoGen has no formal definition of model context.
-
-To start, we should follow [MEAI](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.ai?view=net-9.0-pp).
-
-This document describes the data types from Python perspective,
-while for .NET, we should directly use the MEAI data types.
-
-In Python, we will use `pydantic` to define and operate with these data types.
-
-## Content types
-
-The core data type is `AIContent`, which represents content used by AI services. While the Agent Framework will primarily use the abstracted types, shared across implementations of the underlying Model Client, the `raw_representation` field allows for more tightly-coupled implementations where appropriate.
-
-```python
-class AIContent(BaseModel):
-    raw_representation: Any | None = None
-    additional_properties: dict[str, Any] | None = None
-```
-
-The basic data-bearing types (`TextContent`, `TextReasoningContent`, `DataContent`, and `UriContent`) represent an interface for developers to input data into the system, as well as for agents to output resulting data. In AutoGen, messages containing these content types were considered `ChatMesssage` objects, contrasting with `AgentEvent` objects that were primarily used for internal events (such as tool calls, etc.)
-
-```python
-class TextContent(AIContent):
-    text: str
-
-
-class TextReasoningContent(AIContent):
-    text: str
-
-
-AnyTextualContent = TextContent | TextReasoningContent | "UriContent"
-
-
-class DataContent(AIContent):
-    data: bytes
-    media_type: str
-
-    @property
-    def base64_data(self) -> str:
-        """Returns the data represented by this instance encoded as a Base64 string."""
-        ...
-
-    @property
-    def uri(self) -> str:
-        """Returns the data as a data URI."""
-        ...
-
-
-class UriContent(AIContent):
-    uri: str
-    media_type: str
-
-
-LocatableContent = DataContent | UriContent  # TODO: Consider other names that are more descriptive.
-```
-
-Note that `TextContent` and `TextReasoningContent` do not have an inheritance relationship, and similarly `DataContent` and `UriContent` do not inherit from one-another. In this case, we opt to remain consistent with the .NET-side M.E.AI design. To abstract over both pairs, we provide the `AnyTextualContent` and `LocatableContent` type aliases.
-
-Function calls and results have dedicated content types to represent the ModelClient's request for tool use as well as the means to flow the results back to the agent.
-
-
-```python
-class FunctionCallContent(AIContent):
-    call_id: str
-    name: str
-    arguments: dict[str, Any | None] | None = None
-    exception: Exception | None = None
-
-
-class FunctionResultContent(AIContent):
-    call_id: str
-    result: Any | None = None
-    exception: Exception | None = None
-```
-
-The types contain all necessary error reporting channels (`FunctionCallContext.exception` when the raw function call request cannot be successfully mapped to the input to the tool - likely due to argument mismatch - and `FunctionResultContent.exception` when the tool execution fails). `ErrorContent` is a more general-purpose error reporting type, but one that should be used for reporting non-fatal errors. The way to think about this is that this is akin to a "400" error or a transient "500" error in HTTP parlance.
-
-
-```python
-class ErrorContent(AIContent):
-    error_code: str | None = None
-    details: str | None = None
-    message: str | None
-```
-
-
-Communicating the usage details when invoking a model client is important, but it has traditionally not been well supported in various frameworks, typically ending up relying on the implementor of the assistant consuming the underlying LLM to handle this. Ideally, the Model Client would provide an a-prori means to compute the usage given a message:
-
-
-```python
-
-class TokenEstimator(Protocol):
-    """Estimates the count of tokens in the provided message"""
-    def estimate(message: ChatMessage) -> int:
-        ...
-
-    def estimate_all(message: Sequence[ChatMessage]) -> Generator[int, None, int]
-        ...
-
-
-@runtime_checkable
-class ModelClientWithEstimator(Protocol, ModelClient):
-    @property
-    def token_estimator(self) -> TokenEstimator:
-        """Returns the token estimator for this model client."""
-        ...
-```
-
-As this is not available in the current MEAI design, not generally a capability of native clients of existing hosted models, we will rely on the `UsageDetails` pattern to let the Model Client communicate this data into the Agent consuming it. Custom agents will be responsible for proper aggregation; built-in ones should provide the patterns and ideally implementation helper types. The `UsageDetails` class will provide a canonical additional operator.
-
-```python
-class UsageContent(AIContent):
-    """Usage content type."""
-    details: UsageDetails
-
-
-class UsageDetails:
-    """Provides usage details about a request/response."""
-    input_token_count: int | None = None
-    """The number of tokens in the input."""
-    output_token_count: int | None = None
-    """The number of tokens in the output."""
-    total_token_count: int | None = None
-    """The total number of tokens used to produce the response."""
-    additional_counts: AdditionalCounts | None = None
-    """A dictionary of additional usage counts."""
-```
-
-
-The `AdditionalCounts` class is a `TypedDict` that allows for us to define well-known keys for additional counts (e.g. `thought_token_count` and `image_token_count`), while also allowing for arbitrary keys to be used by the underlying AI service prvoider. We recommend that services prefix their keys with a service identifier (e.g. `openai.`) to avoid collisions, unles using a well-known key.
-
-```python
-class AdditionalCounts(TypedDict, total=False):
-    """Represents well-known additional counts for usage. This is not an exhaustive list.
-
-    Remarks:
-        To make it possible to avoid colisions between similarly-named, but unrelated, additional counts
-        between different AI services, any keys not explicitly defined here should be prefixed with the
-        name of the AI service, e.g., "openai." or "azure.". The separator "." was chosen because it cannot
-        be a legal character in a JSON key.
-
-        Over time additional counts may be added to this class.
-    """
-    thought_token_count: int
-    """The number of tokens used for thought processing."""
-    image_token_count: int
-    """The number of token equivalents used for image processing."""
-```
-
-
-## Tool types
-
-Align with the [MEAI tool types](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.ai.aifunction?view=net-9.0-pp)
-in terms of the core attributes and methods.
-
-See [Tools](./tools.md) for more details.
-
-## Model client and `ChatMessage` types
-
-Align with the MEAI model client types in terms of the core attributes and methods.
-
-See [Models](./models.md) for more details.

docs/design/vector-stores.md

@@ -1,38 +0,0 @@
-# Vector Stores and Embedding Clients
-
-A vector store is component that provides a unified interface for
-interacting with different vector databases, similar to model clients.
-It exposes indexing and querying methods, including vector, text-based
-and hybrid queries.
-
-The details can be filled in based on the existing vector abstraction
-in Semantic Kernel.
-
-The framework provides pre-built vector stores (already exist in
-Semantic Kernel):
-
-- Azure AI Search
-- Cosmos DB
-- Chroma
-- Couchbase
-- Elasticsearch
-- Faiss
-- In-memory
-- JDBC
-- MongoDB
-- Pinecone
-- Postgres
-- Qdrant
-- Redis
-- SQL Server
-- SQLite
-- Volatile
-- Weaviate
-
-Many vector store implementations will require embedding clients
-to function. An embedding client is a component that implements a unified interface
-to interact with different embedding models.
-
-The framework provides a set of pre-built embedding clients:
-
-- TBD.

docs/design/workflows.md

@@ -1,201 +0,0 @@
-# Workflow
-
-The design goal is to create workflows that can be specified in a declarative
-way to allow for easy creation and modification without needing to change the
-underlying code. 
-
-## `Workflow` is Agent
-
-A `Workflow` is an agent composed of other agents. It follows the same interface
-as an agent. This allows for nested workflows, where a workflow can contain other
-workflows.
-
-## Agents in a `Workflow`
-
-Each agent (or a `Workflow`) in a `Workflow` has a thread on which it will
-always run. The thread may be privated, or shared among some or all of the agents.
-
-When do agents share a `thread`?
-
-- When an agent is called through handoff or as a tool by another agent, the caller
-    agent's thread may be shared with the callee agent.
-
-When do agents not share a `thread`?
-
-- When a set of worker agents are called through a "fan-out" and "fan-in" pattern, where the worker
-    agents are called in parallel and the results are combined by an aggregator agent.
-
-Thread sharing can be configured through the `Workflow`'s constructor.
-By default, each agent has its own private thread and no sharing.
-
-See [Threads](threads.md) for more details on how threads work.
-
-## `Workflow` from control flow graph
-
-A `Workflow` can be created from a control flow graph of agents.
-The graph is a directed graph where each node is an agent and each edge
-is a transition between agents. The graph can contain loops
-and conditional transitions.
-
-The control flow graph specifies the order in which agents are called
-and the conditions under which they are called.
-
-```python
-# Create agent instances.
-agent1 = MCPAgent(
-    model_client="OpenAIChatCompletionClient",
-    mcp_server=["MCPServer1", "MCPServer2"],
-)
-agent2 = MCPAgent(
-    model_client="OpenAIChatCompletionClient",
-    mcp_server=["MCPServer3", "MCPServer4"],
-)
-agent3 = MCPAgent(
-    model_client="OpenAIChatCompletionClient",
-    mcp_server="MCPServer5",
-)
-
-# Create a directed graph of agents with conditional loops and transitions.
-# The graph builder validates the graph.
-graph = GraphBuilder() \
-    .add_agent(agent1) \
-    .add_agent(agent2) \
-    .add_agent(agent3) \
-    .add_loop(agent1, agent2, conditions=Any(...)) \
-    .add_transition(agent2, agent3, conditions=Any(..., All(...))]) \
-    .build()
-
-# Create a workflow from the graph.
-workflow = Workflow(graph=graph)
-```
-
-## `Workflow` from message router
-
-By default, each message is delivered to an _inbox_ of every agent in a `Workflow`.
-When an agent is called, the inbox is cleared and the messages are added
-to the thread that is used by the agent.
-
-If multiple agents share a thread, each message is added exactly once to the thread.
-
-To customize the message flow, we can configure how each inbox behaves.
-Each agent's inbox can be configured to only accept messages from a specific sender(s). 
-We can also configure the inbox batch size, time-to-live for messages in the inbox
-and various other parameters that controls how the inbox is processed.
-
-The configuration of agents' inboxes is done using a `Router` object,
-which can be built using a `RouterBuilder` object.
-
-```python
-graph = ...
-
-router = RouterBuilder() \
-    .add_route(source=agent1, target=agent2) \ # Agent2 will receive messages from agent1.
-    .add_route(source=[agent1, agent2], target=agent3, batch_size=10, ttl="1h") \ # Agent3 will receive messages from agent1 and agent2, with a batch size of 10 and a time-to-live of 1 hour.
-    .add_route(source=Router.ANY, target=agent4) \ # Agent4 will receive all messages.
-).build()
-
-# Create a workflow from the graph and router.
-workflow = Workflow(graph=graph, router=router)
-```
-
-You can also skip the graph all together and just create a workflow from the router.
-In this case, all agents will run concurrently to process the messages delivered
-to their inboxes, according to the inbox rules.
-
-```python
-# Create a workflow from the router.
-workflow = Workflow(router=router)
-```
-
-The validation of the router is done as part of the workflow creation, to ensure
-that no gap exists in the routing, and warning for cascading routes.
-
-## Run `Workflow`
-
-It is the same as running an agent.
-
-```python
-# Create a message batch to send to the workflow.
-# The run context is used to pass in the event channel and other context
-# shared by the agents.
-thread = [
-    Message("Hello"),
-    Message("Can you find the file 'foo.txt' for me?"),
-]
-context = RunContext(event_channel="console")
-result = await workflow.run(thread, context=context)
-```
-
-## `Workflow` has a final response
-
-A `Workflow` is expected to have a final response, which is the final response in the 
-result of the last agent in the workflow. The final response is returned as part of the
-`Result` object returned by the `run` method.
-
-This is to ensure the workflow can be used in the same way as an agent. 
-
-## Stopping `Workflow`
-
-A `workflow` may run indefinitely, so it is important to have a way to stop it.
-
-```python
-# Use a stopping condition to stop the workflow when the condition is met.
-# Detail design TBD.
-condition = StopCondition(
-    condition=Any(...),
-    timeout="1h",
-)
-workflow = Workflow(graph=graph, stop_condition=condition)
-```
-
-TBD.
-
-## `Workflow` can be stateless
-
-The workflow state is kept in the thread object as input to the `run` method.
-If not provided, the workflow will create new sub-threads for each agent
-in the workflow for their private threads, otherwise, the workflow will
-use the provided sub-thread.
-
-```python
-# Create a workflow with a graph and router.
-workflow = Workflow(graph=graph, router=router, stop_condition=condition)
-
-# Create a new thread.
-thread = [
-    Message("Hello"),
-    Message("Can you find the file 'foo.txt' for me?"),
-]
-
-# Run the workflow.
-result = await workflow.run(thread, context=context)
-
-# Update the thread with new messages from the user.
-thread = result.thread + [
-    Message("Can you find the file 'bar.txt' for me?"),
-]
-
-# Resume the workflow from where it left off.
-result = await workflow.run(thread, context=context)
-```
-
-Read more about [Threads](threads.md) for more details on threads.
-
-## Pre-defined workflows
-
-The framework ships with a few pre-defined workflows for common orchestration
-patterns. These workflows can be used as-is or as a starting point for
-new developers, however, when using them, you should be aware of the underlying
-implementation and move on to custom workflows when a limit is reached.
-
-The pre-defined workflows are:
-- `Sequential`: A sequential workflow that calls each agent in order,
-  its message flow can be configured separately.
-- `MapReduce`: A map-reduce workflow that splits a task into smaller
-  tasks, runs them in parallel and then combines the results.
-- `RoundRobinGroupChat`: agents are called in a round-robin fashion in a loop.
-- `SelectorGroupChat`: agents are selected on each iteration by the workflow's built-in
-  LLM based selector.
-- `Swarm`: use handoffs.
-
-The predefined workflows are implemented as subclasses of the `Workflow` class.

docs/specs/001-foundry-sdk-alignment.md

@@ -0,0 +1,291 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+contact: markwallace
+date: 2025-08-06
+deciders: markwallace-microsoft, westey-m, quibitron
+consulted: shawnhenry, elijahstraight
+informed: 
+---
+
+# Agent Framework / Foundry SDK Alignment
+
+Agent Framework and Foundry SDK have overlapping functionality but serve different audiences & scenarios. 
+This specification clarifies the positioning of these SDKs to customers, what goes in each and when to use what. 
+
+- **Foundry SDK** is a thin-client SDK for accessing everything available in the agent service and is autogenerated from REST APIs in multiple languages 
+- **Agent Framework SDK** is general-purpose framework for agentic application development, where common agent abstractions enable creating and orchestrating heterogenous agent systems (across local & cloud)
+
+## What is the goal of this feature?
+
+Goals:
+- Developers can seamlessly combine Foundry and Agent Framework SDK's and there is no friction when using both SDKs at the same time
+- Developers can take advantage of the full capabilities supported by the Foundry SDK
+- Developers can create multi-agent orchestrations using Foundry and other agent types
+
+Success Metrics:
+- Complexity of basic samples is comparable to other agent frameworks
+- Developers can easily discover how to use Foundry Agents in Agent Framework multi-agent orchestrations
+
+## What is the problem being solved?
+
+- In Semantic Kernel the Foundry Agent support isn't integrated into the Foundry SDK so there is a disjointed developer UX
+- Customers are confused as to when they should use Foundry SDK versus Semantic Kernel
+
+
+## API Changes
+
+The proposed solution is to add helper methods which allow developers to either retrieve or create an `AIAgent` using a `PersistentAgentsClient` 
+
+- Retrieve an `AIAgent`
+    ```csharp
+    /// <summary>
+    /// Retrieves an existing server side agent, wrapped as a <see cref="ChatClientAgent"/> using the provided <see cref="PersistentAgentsClient"/>.
+    /// </summary>
+    /// <param name="persistentAgentsClient">The <see cref="PersistentAgentsClient"/> to create the <see cref="ChatClientAgent"/> with.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> for the persistent agent.</returns>
+    /// <param name="agentId"> The ID of the server side agent to create a <see cref="ChatClientAgent"/> for.</param>
+    /// <param name="chatOptions">Options that should apply to all runs of the agent.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> instance that can be used to perform operations on the persistent agent.</returns>
+    public static async Task<ChatClientAgent> GetAIAgentAsync(
+        this PersistentAgentsClient persistentAgentsClient,
+        string agentId,
+        ChatOptions? chatOptions = null,
+        CancellationToken cancellationToken = default)
+    ```
+- Create an `AIAgent`
+    ```csharp
+    /// <summary>
+    /// Creates a new server side agent using the provided <see cref="PersistentAgentsClient"/>.
+    /// </summary>
+    /// <param name="persistentAgentsClient">The <see cref="PersistentAgentsClient"/> to create the agent with.</param>
+    /// <param name="model">The model to be used by the agent.</param>
+    /// <param name="name">The name of the agent.</param>
+    /// <param name="description">The description of the agent.</param>
+    /// <param name="instructions">The instructions for the agent.</param>
+    /// <param name="tools">The tools to be used by the agent.</param>
+    /// <param name="toolResources">The resources for the tools.</param>
+    /// <param name="temperature">The temperature setting for the agent.</param>
+    /// <param name="topP">The top-p setting for the agent.</param>
+    /// <param name="responseFormat">The response format for the agent.</param>
+    /// <param name="metadata">The metadata for the agent.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> instance that can be used to perform operations on the newly created agent.</returns>
+    public static async Task<ChatClientAgent> CreateAIAgentAsync(
+        this PersistentAgentsClient persistentAgentsClient,
+        string model,
+        string? name = null,
+        string? description = null,
+        string? instructions = null,
+        IEnumerable<ToolDefinition>? tools = null,
+        ToolResources? toolResources = null,
+        float? temperature = null,
+        float? topP = null,
+        BinaryData? responseFormat = null,
+        IReadOnlyDictionary<string, string>? metadata = null,
+        CancellationToken cancellationToken = default)
+    ```
+- Additional overload using the M.E.AI types:
+    ```csharp
+    /// <summary>
+    /// Creates a new server side agent using the provided <see cref="PersistentAgentsClient"/>.
+    /// </summary>
+    /// <param name="persistentAgentsClient">The <see cref="PersistentAgentsClient"/> to create the agent with.</param>
+    /// <param name="model">The model to be used by the agent.</param>
+    /// <param name="name">The name of the agent.</param>
+    /// <param name="description">The description of the agent.</param>
+    /// <param name="instructions">The instructions for the agent.</param>
+    /// <param name="tools">The tools to be used by the agent.</param>
+    /// <param name="temperature">The temperature setting for the agent.</param>
+    /// <param name="topP">The top-p setting for the agent.</param>
+    /// <param name="responseFormat">The response format for the agent.</param>
+    /// <param name="metadata">The metadata for the agent.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> instance that can be used to perform operations on the newly created agent.</returns>
+    public static async Task<ChatClientAgent> CreateAIAgentAsync(
+        this PersistentAgentsClient persistentAgentsClient,
+        string model,
+        string? name = null,
+        string? description = null,
+        string? instructions = null,
+        IEnumerable<AITool>? tools = null,
+        float? temperature = null,
+        float? topP = null,
+        BinaryData? responseFormat = null,
+        IReadOnlyDictionary<string, string>? metadata = null,
+        CancellationToken cancellationToken = default)
+    ```
+
+
+## E2E Code Samples
+
+### 1. Create and retrieve with Foundry SDK, run with Agent Framework
+
+- [Foundry SDK] Create a `PersistentAgentsClient`
+- [Foundry SDK] Create a `PersistentAgent` using the `PersistentAgentsClient`
+- [Foundry SDK] Retrieve an `AIAgent` using the `PersistentAgentsClient`
+- [Agent Framework SDK] Invoke the `AIAgent` instance and access response from the `AgentRunResponse` 
+- [Foundry SDK] Clean up the agent
+
+
+```csharp
+// Get a client to create server side agents with.
+var persistentAgentsClient = new PersistentAgentsClient(
+    TestConfiguration.AzureAI.Endpoint, new AzureCliCredential());
+
+// Create a persistent agent.
+var persistentAgentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
+    model: TestConfiguration.AzureAI.DeploymentName!,
+    name: JokerName,
+    instructions: JokerInstructions);
+
+// Get the persistent agent we created in the previous step and expose it as an Agent Framework agent.
+AIAgent agent = await persistentAgentsClient.GetAIAgentAsync(persistentAgent.Value.Id);
+
+// Respond to user input.
+var input = "Tell me a joke about a pirate.";
+Console.WriteLine(input);
+Console.WriteLine(await agent.RunAsync(input));
+
+// Delete the persistent agent.
+await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
+```
+
+### 2. Create directly with Foundry SDK, run with Agent Framework
+
+- [Foundry SDK] Create a `PersistentAgentsClient`
+- [Foundry SDK] Create a `AIAgent` using the `PersistentAgentsClient`
+- [Agent Framework SDK] Invoke the `AIAgent` instance and access response from the `AgentRunResponse` 
+- [Foundry SDK] Clean up the agent
+
+```csharp
+// Get a client to create server side agents with.
+var persistentAgentsClient = new PersistentAgentsClient(
+    TestConfiguration.AzureAI.Endpoint, new AzureCliCredential());
+
+// Create a persistent agent and expose it as an Agent Framework agent.
+AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
+    model: TestConfiguration.AzureAI.DeploymentName!,
+    name: JokerName,
+    instructions: JokerInstructions);
+
+// Respond to user input.
+var input = "Tell me a joke about a pirate.";
+Console.WriteLine(input);
+Console.WriteLine(await agent.RunAsync(input));
+
+// Delete the persistent agent.
+await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
+```
+
+### 3. Create directly with Foundry SDK, run with conversation state using Agent Framework
+
+- [Foundry SDK] Create a `PersistentAgentsClient`
+- [Foundry SDK] Create a `AIAgent` using the `PersistentAgentsClient`
+- [Agent Framework SDK] Optionally create an `AgentThread` for the agent run
+- [Agent Framework SDK] Invoke the `AIAgent` instance and access response from the `AgentRunResponse` 
+- [Foundry SDK] Clean up the agent and the agent thread
+
+```csharp
+// Get a client to create server side agents with.
+var persistentAgentsClient = new PersistentAgentsClient(
+    TestConfiguration.AzureAI.Endpoint, new AzureCliCredential());
+
+// Create an Agent Framework agent.
+AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
+    model: TestConfiguration.AzureAI.DeploymentName!,
+    name: JokerName,
+    instructions: JokerInstructions);
+
+// Start a new thread for the agent conversation.
+AgentThread thread = agent.GetNewThread();
+
+// Respond to user input.
+await RunAgentAsync("Tell me a joke about a pirate.");
+await RunAgentAsync("Now add some emojis to the joke.");
+
+// Local function to run agent and display the conversation messages for the thread.
+async Task RunAgentAsync(string input)
+{
+    Console.WriteLine(
+        $"""
+        User: {input}
+        Assistant:
+        {await agent.RunAsync(input, thread)}
+
+        """);
+}
+
+// Cleanup
+await persistentAgentsClient.Threads.DeleteThreadAsync(thread.ConversationId);
+await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
+```
+
+### 4. Create directly with Foundry SDK, orchestrate with Agent Framework
+
+- [Foundry SDK] Create a `PersistentAgentsClient`
+- [Foundry SDK] Create multiple `AIAgent` instances using the `PersistentAgentsClient`
+- [Agent Framework SDK] Create a `SequentialOrchestration` and add all of the agents to it
+- [Agent Framework SDK] Invoke the `SequentialOrchestration` instance and access response from the `AgentRunResponse` 
+- [Foundry SDK] Clean up the agents
+
+```csharp
+// Get a client to create server side agents with.
+var persistentAgentsClient = new PersistentAgentsClient(
+    TestConfiguration.AzureAI.Endpoint, new AzureCliCredential());
+var model = TestConfiguration.OpenAI.ChatModelId;
+
+// Define the agents
+AIAgent analystAgent =
+    await persistentAgentsClient.CreateAIAgentAsync(
+        model,
+        name: "Analyst",
+        instructions:
+        """
+        You are a marketing analyst. Given a product description, identify:
+        - Key features
+        - Target audience
+        - Unique selling points
+        """,
+        description: "An agent that extracts key concepts from a product description.");
+AIAgent writerAgent =
+    await persistentAgentsClient.CreateAIAgentAsync(
+        model,
+        name: "copywriter",
+        instructions:
+        """
+        You are a marketing copywriter. Given a block of text describing features, audience, and USPs,
+        compose a compelling marketing copy (like a newsletter section) that highlights these points.
+        Output should be short (around 150 words), output just the copy as a single text block.
+        """,
+        description: "An agent that writes a marketing copy based on the extracted concepts.");
+AIAgent editorAgent =
+    await persistentAgentsClient.CreateAIAgentAsync(
+        model,
+        name: "editor",
+        instructions:
+        """
+        You are an editor. Given the draft copy, correct grammar, improve clarity, ensure consistent tone,
+        give format and make it polished. Output the final improved copy as a single text block.
+        """,
+        description: "An agent that formats and proofreads the marketing copy.");
+
+// Define the orchestration
+SequentialOrchestration orchestration =
+    new(analystAgent, writerAgent, editorAgent)
+    {
+        LoggerFactory = this.LoggerFactory,
+    };
+
+// Run the orchestration
+string input = "An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours";
+Console.WriteLine($"\n# INPUT: {input}\n");
+AgentRunResponse result = await orchestration.RunAsync(input);
+Console.WriteLine($"\n# RESULT: {result}");
+
+// Cleanup
+await persistentAgentsClient.Administration.DeleteAgentAsync(analystAgent.Id);
+await persistentAgentsClient.Administration.DeleteAgentAsync(writerAgent.Id);
+await persistentAgentsClient.Administration.DeleteAgentAsync(editorAgent.Id);
+```

docs/specs/spec-template.md

@@ -0,0 +1,75 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: {proposed | rejected | accepted | deprecated | … | superseded by [SPEC-0001](0001-spec.md)}
+contact: {person proposing the ADR}
+date: {YYYY-MM-DD when the decision was last updated}
+deciders: {list everyone involved in the decision}
+consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
+informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
+---
+
+# {short title of solved problem and solution}
+
+## What is the goal of this feature?
+
+Make sure to cover:
+1. What is the value we are providing to users
+1. Include one success metric
+1. Implementation free description of outcome
+
+Consult PM on this.
+
+For example:
+
+We want users to be able to refer to external Azure resources easily when consuming them in other features like indexes, agents,
+and evaluations. We know we're successful when 40% of project client users are using connections.
+
+## What is the problem being solved?
+
+Make sure to cover:
+1. Why is this hard today?
+1. Customer pain points?
+1. Reducing system complexity (maintenance costs, latency, etc)?
+
+Consult PM on this.
+
+For example:
+
+Today, users have to understand control plane vs data plane endpoints and use multiple packages to stitch their application
+code together. This makes using our product confusing and also increases the number of dependencies a customer will have
+in their code.
+
+## API Changes
+
+List all new API changes
+
+## E2E Code Samples
+
+Include python or C# examples of how you expect this feature to be used with other things in our system.
+
+For example:
+
+This connection name is unique across the resource. Given a resource name, system should be able to unambiguously resolve a
+connection name. A connection name can be used to pass along connection details to individual features. Services will be able to parse this ID and use it to access the underlying resource. The below example shows how a connection can be used to create a dataset.
+
+```python
+client.datasets.create_dataset(
+    name="evaluation_dataset",
+    file="myblob/product1.pdf",
+    connection = "my-azure-blob-connection"
+)
+```
+
+How to use a connection when creating an `AzureAISearchIndex`
+
+```python
+from azure.ai.projects.models import AzureAISearchIndex
+
+azure_ai_search_index = AzureAISearchIndex(
+    name="azure-search-index",
+    connection="my-ai-search-connection",
+    index_name="my-index-in-azure-search",
+)
+
+created_index = client.indexes.create_index(azure_ai_search_index)
+```

dotnet/.editorconfig

@@ -124,10 +124,12 @@ dotnet_diagnostic.CA1063.severity = warning # Implement IDisposable correctly
 dotnet_diagnostic.CA1064.severity = warning # Exceptions should be public
 dotnet_diagnostic.CA1416.severity = warning # Validate platform compatibility
 dotnet_diagnostic.CA1508.severity = warning # Avoid dead conditional code
+dotnet_diagnostic.CA1805.severity = warning # Member is explicitly initialized to its default value
+dotnet_diagnostic.CA1822.severity = suggestion # Member does not access instance data and can be marked as static
 dotnet_diagnostic.CA1852.severity = warning # Sealed classes
 dotnet_diagnostic.CA1859.severity = warning # Use concrete types when possible for improved performance
 dotnet_diagnostic.CA1860.severity = warning # Prefer comparing 'Count' to 0 rather than using 'Any()', both for clarity and for performance
-dotnet_diagnostic.CA2000.severity = warning # Call System.IDisposable.Dispose on object before all references to it are out of scope
+dotnet_diagnostic.CA2007.severity = warning # Do not directly await a Task
 dotnet_diagnostic.CA2201.severity = warning # Exception type System.Exception is not sufficiently specific
 
 dotnet_diagnostic.IDE0001.severity = warning # Simplify name
@@ -135,7 +137,6 @@ dotnet_diagnostic.IDE0005.severity = warning # Remove unnecessary using directiv
 dotnet_diagnostic.IDE0009.severity = warning # Add this or Me qualification
 dotnet_diagnostic.IDE0011.severity = warning # Add braces
 dotnet_diagnostic.IDE0018.severity = warning # Inline variable declaration
-
 dotnet_diagnostic.IDE0032.severity = warning # Use auto-implemented property
 dotnet_diagnostic.IDE0034.severity = warning # Simplify 'default' expression
 dotnet_diagnostic.IDE0035.severity = warning # Remove unreachable code
@@ -151,12 +152,44 @@ dotnet_diagnostic.IDE0073.severity = warning # Require file header
 dotnet_diagnostic.IDE0082.severity = warning # Convert typeof to nameof
 dotnet_diagnostic.IDE0090.severity = warning # Simplify new expression
 dotnet_diagnostic.IDE0161.severity = warning # Use file-scoped namespace
+dotnet_diagnostic.IDE0280.severity = warning # Use nameof
+
+dotnet_diagnostic.VSTHRD111.severity = warning # Use .ConfigureAwait(bool)
+dotnet_diagnostic.VSTHRD200.severity = warning # Use Async suffix for async methods
+
+dotnet_diagnostic.RCS1021.severity = warning # Use expression-bodied lambda.
+dotnet_diagnostic.RCS1061.severity = warning # Merge 'if' with nested 'if'.
+dotnet_diagnostic.RCS1069.severity = warning # Remove unnecessary case label.
+dotnet_diagnostic.RCS1077.severity = warning # Optimize LINQ method call.
+dotnet_diagnostic.RCS1118.severity = warning # Mark local variable as const.
+dotnet_diagnostic.RCS1124.severity = warning # Inline local variable.
+dotnet_diagnostic.RCS1129.severity = warning # Remove redundant field initialization.
+dotnet_diagnostic.RCS1146.severity = warning # Use conditional access.
+dotnet_diagnostic.RCS1170.severity = warning # Use read-only auto-implemented property.
+dotnet_diagnostic.RCS1173.severity = warning # Use coalesce expression instead of 'if'.
+dotnet_diagnostic.RCS1186.severity = warning # Use Regex instance instead of static method.
+dotnet_diagnostic.RCS1188.severity = warning # Remove redundant auto-property initialization.
+dotnet_diagnostic.RCS1197.severity = suggestion # Optimize StringBuilder.AppendLine call.
+dotnet_diagnostic.RCS1201.severity = suggestion # Use method chaining.
+
+dotnet_diagnostic.IDE0001.severity = warning # Simplify name
+dotnet_diagnostic.IDE0002.severity = warning # Simplify member access
+dotnet_diagnostic.IDE0004.severity = warning # Remove unnecessary cast
+dotnet_diagnostic.IDE0032.severity = warning # Use auto property
+dotnet_diagnostic.IDE0035.severity = warning # Remove unreachable code
+dotnet_diagnostic.IDE0047.severity = warning # Parentheses can be removed
+dotnet_diagnostic.IDE0051.severity = warning # Remove unused private member
+dotnet_diagnostic.IDE0052.severity = warning # Remove unread private member
+dotnet_diagnostic.IDE0059.severity = warning # Unnecessary assignment of a value
+dotnet_diagnostic.IDE0110.severity = warning # Remove unnecessary discards
+dotnet_diagnostic.IDE1006.severity = warning # Naming rule violations
 
 # Suppressed diagnostics
 dotnet_diagnostic.CA1002.severity = none # Change 'List<string>' in '...' to use 'Collection<T>' ...
-dotnet_diagnostic.CA1031.severity = suggestion # Do not catch general exception types
+dotnet_diagnostic.CA1031.severity = none # Do not catch general exception types
 dotnet_diagnostic.CA1032.severity = none # We're using RCS1194 which seems to cover more ctors
 dotnet_diagnostic.CA1034.severity = none # Do not nest type. Alternatively, change its accessibility so that it is not externally visible
+dotnet_diagnostic.CA1054.severity = none # Uri parameters should not be strings
 dotnet_diagnostic.CA1062.severity = none # Disable null check, C# already does it for us
 dotnet_diagnostic.CA1303.severity = none # Do not pass literals as localized parameters
 dotnet_diagnostic.CA1305.severity = none # Operation could vary based on current user's locale settings
@@ -165,51 +198,40 @@ dotnet_diagnostic.CA1508.severity = none # Avoid dead conditional code. Too many
 dotnet_diagnostic.CA1510.severity = none # ArgumentNullException.Throw
 dotnet_diagnostic.CA1512.severity = none # ArgumentOutOfRangeException.Throw
 dotnet_diagnostic.CA1515.severity = none # Making public types from exes internal
-dotnet_diagnostic.CA1805.severity = none # Member is explicitly initialized to its default value
-dotnet_diagnostic.CA1822.severity = none # Member does not access instance data and can be marked as static
+dotnet_diagnostic.CA1707.severity = none # Identifiers should not contain underscores
+dotnet_diagnostic.CA1846.severity = none # Prefer 'AsSpan' over 'Substring'
 dotnet_diagnostic.CA1848.severity = none # For improved performance, use the LoggerMessage delegates
 dotnet_diagnostic.CA1849.severity = none # Use async equivalent; analyzer is currently noisy
 dotnet_diagnostic.CA1865.severity = none # StartsWith(char)
 dotnet_diagnostic.CA1867.severity = none # EndsWith(char)
-dotnet_diagnostic.CA2007.severity = none # Do not directly await a Task
+dotnet_diagnostic.CS1998.severity = none # async method lacks 'await' operators and will run synchronously
+dotnet_diagnostic.CA2000.severity = none # Call System.IDisposable.Dispose on object before all references to it are out of scope
 dotnet_diagnostic.CA2225.severity = none # Operator overloads have named alternates
 dotnet_diagnostic.CA2227.severity = none # Change to be read-only by removing the property setter
+dotnet_diagnostic.CA2249.severity = suggestion # Consider using 'Contains' method instead of 'IndexOf' method
 dotnet_diagnostic.CA2253.severity = none # Named placeholders in the logging message template should not be comprised of only numeric characters
 dotnet_diagnostic.CA2253.severity = none # Named placeholders in the logging message template should not be comprised of only numeric characters
 dotnet_diagnostic.CA2263.severity = suggestion # Use generic overload
-dotnet_diagnostic.CS1998.severity = suggestion # async method lacks 'await' operators and will run synchronously
+dotnet_diagnostic.CA5394.severity = none # Do not use insecure sources of randomness
 
 dotnet_diagnostic.VSTHRD003.severity = none # Waiting on thread from another context
 dotnet_diagnostic.VSTHRD103.severity = none # Use async equivalent; analyzer is currently noisy
 dotnet_diagnostic.VSTHRD111.severity = none # Use .ConfigureAwait(bool) is hidden by default, set to none to prevent IDE from changing on autosave
-dotnet_diagnostic.VSTHRD200.severity = none # Use Async suffix for async methods
-dotnet_diagnostic.xUnit1004.severity = none # Test methods should not be skipped. Remove the Skip property to start running the test again.
 
-dotnet_diagnostic.RCS1021.severity = none # Use expression-bodied lambda.
+dotnet_diagnostic.xUnit1004.severity = none # Test methods should not be skipped. Remove the Skip property to start running the test again.
+dotnet_diagnostic.xUnit1042.severity = none # Untyped data rows
+
 dotnet_diagnostic.RCS1032.severity = none # Remove redundant parentheses.
-dotnet_diagnostic.RCS1061.severity = none # Merge 'if' with nested 'if'.
-dotnet_diagnostic.RCS1069.severity = none # Remove unnecessary case label.
 dotnet_diagnostic.RCS1074.severity = none # Remove redundant constructor.
-dotnet_diagnostic.RCS1077.severity = none # Optimize LINQ method call.
-dotnet_diagnostic.RCS1118.severity = none # Mark local variable as const.
-dotnet_diagnostic.RCS1124.severity = none # Inline local variable.
-dotnet_diagnostic.RCS1129.severity = none # Remove redundant field initialization.
 dotnet_diagnostic.RCS1140.severity = none # Add exception to documentation comment.
 dotnet_diagnostic.RCS1141.severity = none # Add 'param' element to documentation comment.
 dotnet_diagnostic.RCS1142.severity = none # Add 'typeparam' element to documentation comment.
-dotnet_diagnostic.RCS1146.severity = none # Use conditional access.
 dotnet_diagnostic.RCS1151.severity = none # Remove redundant cast.
 dotnet_diagnostic.RCS1158.severity = none # Static member in generic type should use a type parameter.
 dotnet_diagnostic.RCS1161.severity = none # Enum should declare explicit value
 dotnet_diagnostic.RCS1163.severity = none # Unused parameter 'foo'.
-dotnet_diagnostic.RCS1170.severity = none # Use read-only auto-implemented property.
-dotnet_diagnostic.RCS1173.severity = none # Use coalesce expression instead of 'if'.
 dotnet_diagnostic.RCS1181.severity = none # Convert comment to documentation comment.
-dotnet_diagnostic.RCS1186.severity = none # Use Regex instance instead of static method.
-dotnet_diagnostic.RCS1188.severity = none # Remove redundant auto-property initialization.
 dotnet_diagnostic.RCS1189.severity = none # Add region name to #endregion.
-dotnet_diagnostic.RCS1197.severity = none # Optimize StringBuilder.AppendLine call.
-dotnet_diagnostic.RCS1201.severity = none # Use method chaining.
 dotnet_diagnostic.RCS1205.severity = none # Order named arguments according to the order of parameters.
 dotnet_diagnostic.RCS1212.severity = none # Remove redundant assignment.
 dotnet_diagnostic.RCS1217.severity = none # Convert interpolated string to concatenation.
@@ -218,38 +240,28 @@ dotnet_diagnostic.RCS1226.severity = none # Add paragraph to documentation comme
 dotnet_diagnostic.RCS1229.severity = none # Use async/await when necessary.
 dotnet_diagnostic.RCS1234.severity = none # Enum duplicate value
 dotnet_diagnostic.RCS1238.severity = none # Avoid nested ?: operators.
-dotnet_diagnostic.RCS1241.severity = none # Implement IComparable when implementing IComparable<T><T>.
+dotnet_diagnostic.RCS1241.severity = none # Implement IComparable when implementing IComparable<T>
+dotnet_diagnostic.RCS1246.severity = none # Use element access
+dotnet_diagnostic.RCS1261.severity = none # Resource can be disposed asynchronously
 
-dotnet_diagnostic.IDE0001.severity = none # Simplify name
-dotnet_diagnostic.IDE0002.severity = none # Simplify member access
-dotnet_diagnostic.IDE0004.severity = none # Remove unnecessary cast
 dotnet_diagnostic.IDE0010.severity = none # Populate switch
 dotnet_diagnostic.IDE0021.severity = none # Use block body for constructors
 dotnet_diagnostic.IDE0022.severity = none # Use block body for methods
 dotnet_diagnostic.IDE0024.severity = none # Use block body for operator
-dotnet_diagnostic.IDE0035.severity = none # Remove unreachable code
-dotnet_diagnostic.IDE0051.severity = none # Remove unused private member
-dotnet_diagnostic.IDE0052.severity = none # Remove unread private member
-dotnet_diagnostic.IDE0058.severity = none # Remove unused expression value
-dotnet_diagnostic.IDE0059.severity = none # Unnecessary assignment of a value
+dotnet_diagnostic.IDE0042.severity = none # Variable declaration can be deconstructed
+dotnet_diagnostic.IDE0046.severity = none # if statement can be simplified
+dotnet_diagnostic.IDE0056.severity = none # Indexing can be simplified
+dotnet_diagnostic.IDE0057.severity = none # Substring can be simplified
 dotnet_diagnostic.IDE0060.severity = none # Remove unused parameter
 dotnet_diagnostic.IDE0061.severity = none # Use block body for local function
 dotnet_diagnostic.IDE0079.severity = none # Remove unnecessary suppression.
 dotnet_diagnostic.IDE0080.severity = none # Remove unnecessary suppression operator.
 dotnet_diagnostic.IDE0100.severity = none # Remove unnecessary equality operator
-dotnet_diagnostic.IDE0110.severity = none # Remove unnecessary discards
 dotnet_diagnostic.IDE0130.severity = none # Namespace does not match folder structure
-dotnet_diagnostic.IDE0290.severity = none # Use primary constructor
-dotnet_diagnostic.IDE0032.severity = none # Use auto property
 dotnet_diagnostic.IDE0160.severity = none # Use block-scoped namespace
-dotnet_diagnostic.IDE1006.severity = warning # Naming rule violations
-dotnet_diagnostic.IDE0046.severity = suggestion # If statement can be simplified
-dotnet_diagnostic.IDE0056.severity = suggestion # Indexing can be simplified
-dotnet_diagnostic.IDE0057.severity = suggestion # Substring can be simplified
-
-dotnet_diagnostic.CA2007.severity = error # Do not directly await a Task
-dotnet_diagnostic.VSTHRD111.severity = error # Use .ConfigureAwait(bool)
-dotnet_diagnostic.IDE1006.severity = error # Naming rule violations
+dotnet_diagnostic.IDE0290.severity = none # Use primary constructor
+dotnet_diagnostic.IDE0305.severity = none # ToList can be simplified
+dotnet_diagnostic.IDE0330.severity = none # Use 'System.Threading.Lock'
 
 # Testing
 dotnet_diagnostic.Moq1400.severity = none # Explicitly choose a mocking behavior instead of relying on the default (Loose) behavior
@@ -430,3 +442,6 @@ resharper_redundant_using_directive_highlighting = warning # Resharper's "Redund
 resharper_inconsistent_naming_highlighting = warning # Resharper's "Inconsistent naming" highlighting
 resharper_redundant_this_qualifier_highlighting = warning # Resharper's "Redundant 'this' qualifier" highlighting
 resharper_arrange_this_qualifier_highlighting = warning # Resharper's "Arrange 'this' qualifier" highlighting
+csharp_style_prefer_primary_constructors = true:suggestion
+csharp_prefer_system_threading_lock = true:suggestion
+csharp_style_prefer_simple_property_accessors = true:suggestion

dotnet/.vscode/extensions.json

@@ -0,0 +1,5 @@
+{
+    "recommendations": [
+        "ms-dotnettools.csdevkit"
+    ]
+}

dotnet/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "dotnet.defaultSolution": "agent-framework-dotnet.slnx",
+    "git.openRepositoryInParentFolders": "always",
+    "chat.agent.enabled": true
+}

dotnet/.vscode/tasks.json

@@ -0,0 +1,15 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"type": "dotnet",
+			"task": "build",
+			"group": {
+				"kind": "build",
+				"isDefault": true
+			},
+			"problemMatcher": [],
+			"label": "dotnet: build"
+		}
+	]
+}

dotnet/Directory.Build.props

@@ -6,14 +6,16 @@
     <AnalysisMode>AllEnabledByDefault</AnalysisMode>
     <AnalysisLevel>latest</AnalysisLevel>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <LangVersion>12</LangVersion>
+    <LangVersion>13</LangVersion>
     <Nullable>enable</Nullable>
-    <ImplicitUsings>disable</ImplicitUsings>
-    <NoWarn>$(NoWarn);IDE0290;IDE0079;NU5128</NoWarn>
+    <NoWarn>$(NoWarn);NU5128</NoWarn>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <ProjectsCoreTargetFrameworks>net9.0;net8.0</ProjectsCoreTargetFrameworks>
+    <ProjectsDebugCoreTargetFrameworks>net9.0</ProjectsDebugCoreTargetFrameworks>
     <ProjectsTargetFrameworks>net9.0;net8.0;netstandard2.0;net472</ProjectsTargetFrameworks>
     <ProjectsDebugTargetFrameworks>net9.0;net472</ProjectsDebugTargetFrameworks>
     <IsAotCompatible Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net7.0'))">true</IsAotCompatible>
+    <Configurations>Debug;Release;Publish</Configurations>
   </PropertyGroup>
 
   <PropertyGroup>
@@ -22,7 +24,7 @@
   
   <PropertyGroup>
     <!-- Disable NuGet packaging by default. Projects can override. -->
-    <IsPackable>disable</IsPackable>
+    <IsPackable>false</IsPackable>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(Configuration)'=='Publish'">
@@ -31,7 +33,7 @@
 
   <!-- .NET Framework/.NET Standard don't properly support nullable reference types, suppress any warnings for those TFMs -->
   <PropertyGroup Condition=" '$(TargetFramework)' == 'netstandard2.0' OR '$(TargetFramework)' == 'net472' ">
-    <NoWarn>$(NoWarn);CS8604;CS8602</NoWarn>
+    <NoWarn>$(NoWarn);nullable</NoWarn>
   </PropertyGroup>
 
   <PropertyGroup>

dotnet/Directory.Packages.props

@@ -5,57 +5,124 @@
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
     <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
   </PropertyGroup>
+  <PropertyGroup>
+    <!-- Aspire -->
+    <AspireAppHostSdkVersion>13.0.0</AspireAppHostSdkVersion>
+  </PropertyGroup>
   <ItemGroup>
+    <!-- Aspire.* -->
+    <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="13.0.0-preview.1.25560.3" />
+    <PackageVersion Include="Aspire.Hosting.AppHost" Version="$(AspireAppHostSdkVersion)" />
+    <PackageVersion Include="Aspire.Hosting.Azure.CognitiveServices" Version="$(AspireAppHostSdkVersion)" />
+    <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
+    <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0-beta.440" />
     <!-- Azure.* -->
-    <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="9.3.1-preview.1.25305.6" />
-    <PackageVersion Include="Aspire.Hosting.AppHost" Version="9.3.1" />
-    <PackageVersion Include="Aspire.Hosting.Azure.CognitiveServices" Version="9.3.1" />
-    <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.1" />
-    <PackageVersion Include="Azure.AI.OpenAI" Version="2.2.0-beta.5" />
-    <PackageVersion Include="Azure.Identity" Version="1.14.2" />
-    <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="9.6.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.AzureAIInference" Version="9.7.1-preview.1.25365.4" />
-    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="9.7.0" />
-    <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="9.3.1" />
-    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.12.0" />
+    <PackageVersion Include="Azure.AI.Projects" Version="1.2.0-beta.3" />
+    <PackageVersion Include="Azure.AI.Projects.OpenAI" Version="1.0.0-beta.3" />
+    <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.7" />
+    <PackageVersion Include="Azure.AI.OpenAI" Version="2.5.0-beta.1" />
+    <PackageVersion Include="Azure.Identity" Version="1.17.0" />
+    <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.4.0" />
     <!-- System.* -->
-    <PackageVersion Include="System.Linq.Async" Version="6.0.3" />
-    <PackageVersion Include="System.Text.Json" Version="9.0.7" />
-    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="9.0.7" />
-    <PackageVersion Include="System.Threading.Channels" Version="9.0.7" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.8.0" />
+    <PackageVersion Include="System.CodeDom" Version="10.0.0" />
+    <PackageVersion Include="System.Collections.Immutable" Version="10.0.0" />
+    <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
+    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.0" />
+    <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.0" />
+    <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.0" />
+    <PackageVersion Include="System.Text.Json" Version="10.0.0" />
+    <PackageVersion Include="System.Threading.Channels" Version="10.0.0" />
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
     <!-- OpenTelemetry -->
-    <PackageVersion Include="OpenTelemetry" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />
+    <PackageVersion Include="OpenTelemetry" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Api" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.13.0" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.13.0" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.13.0" />
+    <!-- Microsoft.AspNetCore.* -->
+    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="9.0.11" />
+    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="9.7.1" />
-    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="9.7.1-preview.1.25365.4" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="9.7.1" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="9.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.Abstractions" Version="9.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="9.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="9.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="9.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="9.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="9.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Logging" Version="9.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="9.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Testing" Version="9.0.7" />
+    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.AzureAIInference" Version="10.0.0-preview.1.25559.3" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.0.0-preview.1.25559.3" />
+    <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
+    <!-- Vector Stores -->
+    <PackageVersion Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.67.0-preview" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Connectors.Qdrant" Version="1.67.0-preview" />
+    <!-- Semantic Kernel -->
+    <PackageVersion Include="Microsoft.SemanticKernel" Version="1.67.0" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Agents.Core" Version="1.67.0" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Agents.OpenAI" Version="1.67.0-preview" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Agents.AzureAI" Version="1.67.0-preview" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.67.0" />
     <!-- Agent SDKs -->
-    <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.1.151" />
+    <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.2.41" />
+    <!-- M365 Agents SDK -->
+    <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
+    <PackageVersion Include="Microsoft.Agents.Authentication.Msal" Version="1.2.41" />
+    <PackageVersion Include="Microsoft.Agents.Hosting.AspNetCore" Version="1.2.41" />
+    <!-- A2A -->
+    <PackageVersion Include="A2A" Version="0.3.3-preview" />
+    <PackageVersion Include="A2A.AspNetCore" Version="0.3.3-preview" />
+    <!-- MCP -->
+    <PackageVersion Include="ModelContextProtocol" Version="0.4.0-preview.3" />
+    <!-- Inference SDKs -->
+    <PackageVersion Include="Anthropic.SDK" Version="5.8.0" />
+    <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.4.6" />
+    <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
+    <PackageVersion Include="OllamaSharp" Version="5.4.8" />
+    <PackageVersion Include="OpenAI" Version="2.6.0" />
     <!-- Identity -->
-    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.74.1" />
+    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.78.0" />
+    <!-- Workflows -->
+    <PackageVersion Include="Microsoft.Bot.ObjectModel" Version="1.2025.1106.1" />
+    <PackageVersion Include="Microsoft.Bot.ObjectModel.Json" Version="1.2025.1106.1" />
+    <PackageVersion Include="Microsoft.Bot.ObjectModel.PowerFx" Version="1.2025.1106.1" />
+    <PackageVersion Include="Microsoft.PowerFx.Interpreter" Version="1.5.0-build.20251008-1002" />
+    <!-- Durable Task -->
+    <PackageVersion Include="Microsoft.DurableTask.Client" Version="1.16.2" />
+    <PackageVersion Include="Microsoft.DurableTask.Client.AzureManaged" Version="1.16.2-preview.1" />
+    <PackageVersion Include="Microsoft.DurableTask.Worker" Version="1.16.2" />
+    <PackageVersion Include="Microsoft.DurableTask.Worker.AzureManaged" Version="1.16.2-preview.1" />
+    <!-- Azure Functions -->
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker" Version="2.50.0" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="2.50.0" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" Version="1.9.0" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" Version="1.0.0" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.3.0" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="2.1.0" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Mcp" Version="1.0.0" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Sdk" Version="2.0.7" />
+    <!-- Community -->
+    <PackageVersion Include="System.Linq.Async" Version="6.0.3" />
     <!-- Test -->
-    <PackageVersion Include="FluentAssertions" Version="8.5.0" />
-    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageVersion Include="FluentAssertions" Version="8.8.0" />
+    <PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="9.0.11" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.0.0" />
     <PackageVersion Include="Moq" Version="[4.18.4]" />
     <PackageVersion Include="xunit" Version="2.9.3" />
     <PackageVersion Include="xunit.abstractions" Version="2.0.3" />
@@ -65,8 +132,8 @@
     <!-- Symbols -->
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
     <!-- Toolset -->
-    <PackageVersion Include="Microsoft.Net.Compilers.Toolset" Version="4.12.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="9.0.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.100" />
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
@@ -81,12 +148,12 @@
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageVersion Include="Moq.Analyzers" Version="0.3.0" />
+    <PackageVersion Include="Moq.Analyzers" Version="0.3.1" />
     <PackageReference Include="Moq.Analyzers">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
-    <PackageVersion Include="Roslynator.Analyzers" Version="[4.14.0]" />
+    <PackageVersion Include="Roslynator.Analyzers" Version="[4.14.1]" />
     <PackageReference Include="Roslynator.Analyzers">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
@@ -102,4 +169,4 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
-</Project>
+</Project>

dotnet/README.md

@@ -0,0 +1,41 @@
+# 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
+
+```c#
+using System;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")!;
+
+var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+    .GetOpenAIResponseClient(deploymentName)
+    .CreateAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+
+Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
+```
+
+## 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
+
+## Agent Framework Documentation
+
+- [Documentation](https://learn.microsoft.com/agent-framework/)
+- [Agent Framework Repository](https://github.com/microsoft/agent-framework)
+- [Design Documents](../docs/design)
+- [Architectural Decision Records](../docs/decisions)
+- [MSFT Learn Docs](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview)

dotnet/agent-framework-dotnet.slnx

@@ -4,49 +4,212 @@
     <BuildType Name="Publish" />
     <BuildType Name="Release" />
   </Configurations>
-  <Folder Name="/ConformanceTests/">
-    <Project Path="tests/AgentConformance.IntegrationTests/AgentConformance.IntegrationTests.csproj">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
-    <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" Id="e91d4745-7ccd-4de8-9bc0-31081f540038">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
-    <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
-    <Project Path="tests/OpenAIAssistant.IntegrationTests/OpenAIAssistant.IntegrationTests.csproj" Id="a35b6971-6f27-4904-a168-8e12b229cced">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
-    <Project Path="tests/OpenAIChatCompletion.IntegrationTests/OpenAIChatCompletion.IntegrationTests.csproj">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
-    <Project Path="tests/OpenAIResponse.IntegrationTests/OpenAIResponse.IntegrationTests.csproj">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
-  </Folder>
-  <Folder Name="/Demos/">
-    <Project Path="demos/MinimalConsole/MinimalConsole.csproj">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
-  </Folder>
   <Folder Name="/Samples/">
-    <Project Path="samples/GettingStarted/GettingStarted.csproj">
-      <BuildType Solution="Publish|*" Project="Debug" />
-    </Project>
+    <File Path="samples/README.md" />
   </Folder>
-  <Folder Name="/Samples/HelloHttpApi/">
-    <Project Path="samples/HelloHttpApi/HelloHttpApi.ApiService/HelloHttpApi.ApiService.csproj">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
-    <Project Path="samples/HelloHttpApi/HelloHttpApi.AppHost/HelloHttpApi.AppHost.csproj" Id="17db642e-bf19-413c-bdb1-ccbccc753d7b">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
-    <Project Path="samples/HelloHttpApi/HelloHttpApi.ServiceDefaults/HelloHttpApi.ServiceDefaults.csproj">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
-    <Project Path="samples/HelloHttpApi/HelloHttpApi.Web/HelloHttpApi.Web.csproj">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
+  <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>
+  <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>
+  <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>
+  <Folder Name="/Samples/AzureFunctions/">
+    <File Path="samples/AzureFunctions/.editorconfig" />
+    <File Path="samples/AzureFunctions/README.md" />
+    <Project Path="samples/AzureFunctions/01_SingleAgent/01_SingleAgent.csproj" />
+    <Project Path="samples/AzureFunctions/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
+    <Project Path="samples/AzureFunctions/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
+    <Project Path="samples/AzureFunctions/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
+    <Project Path="samples/AzureFunctions/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
+    <Project Path="samples/AzureFunctions/06_LongRunningTools/06_LongRunningTools.csproj" />
+    <Project Path="samples/AzureFunctions/07_AgentAsMcpTool/07_AgentAsMcpTool.csproj" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/">
+    <File Path="samples/GettingStarted/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" />
+  </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_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_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>
+  <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_3rdPartyThreadStorage/Agent_Step07_3rdPartyThreadStorage.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" />
+  </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>
+  <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>
+  <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" />
+  </Folder>
+  <Folder Name="/Samples/Purview/" />
+  <Folder Name="/Samples/Purview/AgentWithPurview/">
+    <Project Path="samples/Purview/AgentWithPurview/AgentWithPurview.csproj" />
+  </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" />
+  </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" />
+  </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>
+  <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" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/Declarative/Examples/">
+    <File Path="../workflow-samples/ConfirmInput.yaml" />
+    <File Path="../workflow-samples/DeepResearch.yaml" />
+    <File Path="../workflow-samples/Marketing.yaml" />
+    <File Path="../workflow-samples/MathChat.yaml" />
+    <File Path="../workflow-samples/README.md" />
+    <File Path="../workflow-samples/wttr.json" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/SharedStates/">
+    <Project Path="samples/GettingStarted/Workflows/SharedStates/SharedStates.csproj" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/Loop/">
+    <Project Path="samples/GettingStarted/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/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>
+  <Folder Name="/Samples/GettingStarted/Workflows/HumanInTheLoop/">
+    <Project Path="samples/GettingStarted/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>
+  <Folder Name="/Samples/GettingStarted/Workflows/Visualization/">
+    <Project Path="samples/GettingStarted/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>
+  <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>
+  <Folder Name="/Samples/M365Agent/">
+    <Project Path="samples/M365Agent/M365Agent.csproj" />
   </Folder>
   <Folder Name="/Solution Items/">
     <File Path=".editorconfig" />
@@ -54,27 +217,34 @@
     <File Path="Directory.Build.props" />
     <File Path="Directory.Build.targets" />
     <File Path="Directory.Packages.props" />
-  </Folder>
-  <Folder Name="/Solution Items/nuget/">
-    <File Path="nuget/icon.png" />
-    <File Path="nuget/nuget-package.props" />
-    <File Path="nuget/NUGET.md" />
-  </Folder>
-  <Folder Name="/Solution Items/tests/">
-    <File Path="tests/.editorconfig" />
-    <File Path="tests/Directory.Build.props" />
+    <File Path="global.json" />
+    <File Path="nuget.config" />
   </Folder>
   <Folder Name="/Solution Items/.github/" />
+  <Folder Name="/Solution Items/.github/upgrades/" />
+  <Folder Name="/Solution Items/.github/upgrades/prompts/">
+    <File Path="../.github/upgrades/prompts/SemanticKernelToAgentFramework.md" />
+  </Folder>
   <Folder Name="/Solution Items/.github/workflows/">
     <File Path="../.github/workflows/dotnet-build-and-test.yml" />
     <File Path="../.github/workflows/dotnet-check-coverage.ps1" />
     <File Path="../.github/workflows/dotnet-format.yml" />
   </Folder>
+  <Folder Name="/Solution Items/demos/">
+    <File Path="demos/.editorconfig" />
+    <File Path="demos/Directory.Build.props" />
+  </Folder>
   <Folder Name="/Solution Items/docs/" />
   <Folder Name="/Solution Items/docs/decisions/">
     <File Path="../docs/decisions/0001-agent-run-response.md" />
-    <File Path="../docs/decisions/0001-agent-tools.md" />
-    <File Path="../docs/decisions/0002-agent-opentelemetry-instrumentation.md" />
+    <File Path="../docs/decisions/0002-agent-tools.md" />
+    <File Path="../docs/decisions/0003-agent-opentelemetry-instrumentation.md" />
+    <File Path="../docs/decisions/0004-foundry-sdk-extensions.md" />
+    <File Path="../docs/decisions/0005-python-naming-conventions.md" />
+    <File Path="../docs/decisions/0006-userapproval.md" />
+    <File Path="../docs/decisions/0007-agent-filtering-middleware.md" />
+    <File Path="../docs/decisions/0008-python-subpackages.md" />
+    <File Path="../docs/decisions/0009-support-long-running-operations.md" />
     <File Path="../docs/decisions/adr-short-template.md" />
     <File Path="../docs/decisions/adr-template.md" />
     <File Path="../docs/decisions/README.md" />
@@ -85,22 +255,10 @@
     <File Path="eng/MSBuild/Shared.props" />
     <File Path="eng/MSBuild/Shared.targets" />
   </Folder>
-  <Folder Name="/Solution Items/src/Shared/" />
-  <Folder Name="/Solution Items/src/Shared/Throw/">
-    <File Path="src/Shared/Throw/README.md" />
-    <File Path="src/Shared/Throw/Throw.cs" />
-  </Folder>
-  <Folder Name="/Solution Items/src/Shared/IntegrationTests/">
-    <File Path="src/Shared/IntegrationTests/AzureAIConfiguration.cs" />
-    <File Path="src/Shared/IntegrationTests/OpenAIConfiguration.cs" />
-    <File Path="src/Shared/IntegrationTests/README.md" />
-  </Folder>
-  <Folder Name="/Solution Items/src/Shared/Samples/">
-    <File Path="src/Shared/Samples/README.md" />
-    <File Path="src/Shared/Samples/BaseSample.cs" />
-    <File Path="src/Shared/Samples/TestConfiguration.cs" />
-    <File Path="src/Shared/Samples/TextOutputHelperExtensions.cs" />
-    <File Path="src/Shared/Samples/XunitLogger.cs" />
+  <Folder Name="/Solution Items/nuget/">
+    <File Path="nuget/icon.png" />
+    <File Path="nuget/nuget-package.props" />
+    <File Path="nuget/NUGET.md" />
   </Folder>
   <Folder Name="/Solution Items/samples/">
     <File Path="samples/.editorconfig" />
@@ -114,13 +272,17 @@
     <File Path="src/LegacySupport/CallerAttributes/CallerArgumentExpressionAttribute.cs" />
     <File Path="src/LegacySupport/CallerAttributes/README.md" />
   </Folder>
+  <Folder Name="/Solution Items/src/LegacySupport/CompilerFeatureRequiredAttribute/">
+    <File Path="src/LegacySupport/CompilerFeatureRequiredAttribute/CompilerFeatureRequiredAttribute.cs" />
+    <File Path="src/LegacySupport/CompilerFeatureRequiredAttribute/README.md" />
+  </Folder>
   <Folder Name="/Solution Items/src/LegacySupport/DiagnosticAttributes/">
     <File Path="src/LegacySupport/DiagnosticAttributes/NullableAttributes.cs" />
     <File Path="src/LegacySupport/DiagnosticAttributes/README.md" />
   </Folder>
   <Folder Name="/Solution Items/src/LegacySupport/DiagnosticClasses/">
-    <File Path="src/LegacySupport/DiagnosticClasses/UnreachableException.cs" />
     <File Path="src/LegacySupport/DiagnosticClasses/README.md" />
+    <File Path="src/LegacySupport/DiagnosticClasses/UnreachableException.cs" />
   </Folder>
   <Folder Name="/Solution Items/src/LegacySupport/ExperimentalAttribute/">
     <File Path="src/LegacySupport/ExperimentalAttribute/ExperimentalAttribute.cs" />
@@ -130,6 +292,10 @@
     <File Path="src/LegacySupport/IsExternalInit/IsExternalInit.cs" />
     <File Path="src/LegacySupport/IsExternalInit/README.md" />
   </Folder>
+  <Folder Name="/Solution Items/src/LegacySupport/RequiredMemberAttribute/">
+    <File Path="src/LegacySupport/RequiredMemberAttribute/README.md" />
+    <File Path="src/LegacySupport/RequiredMemberAttribute/RequiredMemberAttribute.cs" />
+  </Folder>
   <Folder Name="/Solution Items/src/LegacySupport/TrimAttributes/">
     <File Path="src/LegacySupport/TrimAttributes/DynamicallyAccessedMembersAttribute.cs" />
     <File Path="src/LegacySupport/TrimAttributes/DynamicallyAccessedMemberTypes.cs" />
@@ -138,30 +304,88 @@
     <File Path="src/LegacySupport/TrimAttributes/RequiresUnreferencedCodeAttribute.cs" />
     <File Path="src/LegacySupport/TrimAttributes/UnconditionalSuppressMessageAttribute.cs" />
   </Folder>
-  <Folder Name="/src/">
-    <Project Path="src/Microsoft.Agents.Orchestration/Microsoft.Agents.Orchestration.csproj" />
-    <Project Path="src/Microsoft.Extensions.AI.Agents.Abstractions/Microsoft.Extensions.AI.Agents.Abstractions.csproj" />
-    <Project Path="src/Microsoft.Extensions.AI.Agents.AzureAI/Microsoft.Extensions.AI.Agents.AzureAI.csproj" />
-    <Project Path="src/Microsoft.Extensions.AI.Agents.CopilotStudio/Microsoft.Extensions.AI.Agents.CopilotStudio.csproj" />
-    <Project Path="src/Microsoft.Extensions.AI.Agents.OpenAI/Microsoft.Extensions.AI.Agents.OpenAI.csproj" />
-    <Project Path="src/Microsoft.Extensions.AI.Agents.Runtime.Abstractions/Microsoft.Extensions.AI.Agents.Runtime.Abstractions.csproj" />
-    <Project Path="src/Microsoft.Extensions.AI.Agents.Runtime/Microsoft.Extensions.AI.Agents.Runtime.csproj" Id="35d72ad5-61e1-45cc-a9ad-fa8490dbd146">
-      <BuildType Solution="Publish|*" Project="Release" />
-    </Project>
-    <Project Path="src/Microsoft.Extensions.AI.Agents/Microsoft.Extensions.AI.Agents.csproj" />
+  <Folder Name="/Solution Items/src/Shared/" />
+  <Folder Name="/Solution Items/src/Shared/Demos/">
+    <File Path="src/Shared/Demos/README.md" />
+    <File Path="src/Shared/Demos/SampleEnvironment.cs" />
   </Folder>
-  <Folder Name="/UnitTests/">
-    <Project Path="tests/Microsoft.Agents.Orchestration.UnitTests/Microsoft.Agents.Orchestration.UnitTests.csproj">
-      <BuildType Solution="Publish|*" Project="Debug" />
-    </Project>
-    <Project Path="tests/Microsoft.Extensions.AI.Agents.Abstractions.UnitTests/Microsoft.Extensions.AI.Agents.Abstractions.UnitTests.csproj">
-      <BuildType Solution="Publish|*" Project="Debug" />
-    </Project>
-    <Project Path="tests/Microsoft.Extensions.AI.Agents.Runtime.Abstractions.UnitTests/Microsoft.Extensions.AI.Agents.Runtime.Abstractions.UnitTests.csproj">
-      <BuildType Solution="Publish|*" Project="Debug" />
-    </Project>
-    <Project Path="tests/Microsoft.Extensions.AI.Agents.UnitTests/Microsoft.Extensions.AI.Agents.UnitTests.csproj">
-      <BuildType Solution="Publish|*" Project="Debug" />
-    </Project>
+  <Folder Name="/Solution Items/src/Shared/IntegrationTests/">
+    <File Path="src/Shared/IntegrationTests/AzureAIConfiguration.cs" />
+    <File Path="src/Shared/IntegrationTests/Mem0Configuration.cs" />
+    <File Path="src/Shared/IntegrationTests/OpenAIConfiguration.cs" />
+    <File Path="src/Shared/IntegrationTests/README.md" />
+  </Folder>
+  <Folder Name="/Solution Items/src/Shared/Samples/">
+    <File Path="src/Shared/Samples/BaseSample.cs" />
+    <File Path="src/Shared/Samples/README.md" />
+    <File Path="src/Shared/Samples/TestConfiguration.cs" />
+    <File Path="src/Shared/Samples/TextOutputHelperExtensions.cs" />
+    <File Path="src/Shared/Samples/XunitLogger.cs" />
+  </Folder>
+  <Folder Name="/Solution Items/src/Shared/Throw/">
+    <File Path="src/Shared/Throw/README.md" />
+    <File Path="src/Shared/Throw/Throw.cs" />
+  </Folder>
+  <Folder Name="/Solution Items/tests/">
+    <File Path="tests/.editorconfig" />
+    <File Path="tests/Directory.Build.props" />
+  </Folder>
+  <Folder Name="/src/">
+    <Project Path="src/Microsoft.Agents.AI.A2A/Microsoft.Agents.AI.A2A.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.AGUI/Microsoft.Agents.AI.AGUI.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.AzureAI.Persistent/Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.AzureAI/Microsoft.Agents.AI.AzureAI.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.CopilotStudio/Microsoft.Agents.AI.CopilotStudio.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.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Hosting.AzureFunctions/Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Hosting.OpenAI/Microsoft.Agents.AI.Hosting.OpenAI.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Hosting/Microsoft.Agents.AI.Hosting.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Mem0/Microsoft.Agents.AI.Mem0.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.OpenAI/Microsoft.Agents.AI.OpenAI.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.AzureAI/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
+    <Project Path="src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj" />
+  </Folder>
+  <Folder Name="/Tests/" />
+  <Folder Name="/Tests/IntegrationTests/">
+    <Project Path="tests/AgentConformance.IntegrationTests/AgentConformance.IntegrationTests.csproj" />
+    <Project Path="tests/AzureAI.IntegrationTests/AzureAI.IntegrationTests.csproj" />
+    <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
+    <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.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" />
+    <Project Path="tests/Microsoft.Agents.AI.Mem0.IntegrationTests/Microsoft.Agents.AI.Mem0.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests.csproj" />
+    <Project Path="tests/OpenAIAssistant.IntegrationTests/OpenAIAssistant.IntegrationTests.csproj" />
+    <Project Path="tests/OpenAIChatCompletion.IntegrationTests/OpenAIChatCompletion.IntegrationTests.csproj" />
+    <Project Path="tests/OpenAIResponse.IntegrationTests/OpenAIResponse.IntegrationTests.csproj" />
+  </Folder>
+  <Folder Name="/Tests/UnitTests/">
+    <Project Path="tests/Microsoft.Agents.AI.A2A.UnitTests/Microsoft.Agents.AI.A2A.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Abstractions.UnitTests/Microsoft.Agents.AI.Abstractions.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.AGUI.UnitTests/Microsoft.Agents.AI.AGUI.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.AzureAI.UnitTests/Microsoft.Agents.AI.AzureAI.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.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.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" />
+    <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Hosting.UnitTests/Microsoft.Agents.AI.Hosting.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Mem0.UnitTests/Microsoft.Agents.AI.Mem0.UnitTests.csproj" />
+    <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.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj" />
   </Folder>
 </Solution>

dotnet/demos/.editorconfig

@@ -1,8 +0,0 @@
-# Suppressing errors for Sample projects under dotnet/samples folder
-[*.cs]
-dotnet_diagnostic.CA2007.severity = none # Do not directly await a Task
-dotnet_diagnostic.CS1591.severity = none # Missing XML comment for publicly visible type or member
-dotnet_diagnostic.IDE1006.severity = warning # Naming rule violations
-dotnet_diagnostic.VSTHRD111.severity = none # Use .ConfigureAwait(bool) is hidden by default, set to none to prevent IDE from changing on autosave
-dotnet_diagnostic.CA1716.severity = none # Add summary to documentation comment.
-dotnet_diagnostic.CA2000.severity = none # Call System.IDisposable.Dispose on object before all references to it are out of scope

dotnet/demos/MinimalConsole/Program.cs

@@ -1,27 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System;
-using System.ComponentModel;
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Extensions.AI;
-using Microsoft.Extensions.AI.Agents;
-
-[Description("Get the weather for a given location.")]
-static string GetWeather([Description("The location to get the weather for.")] string location)
-{
-    return $"The weather in {location} is cloudy with a high of 15°C.";
-}
-
-IChatClient chatClient = new AzureOpenAIClient(
-    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!),
-    new AzureCliCredential())
-     .GetChatClient("gpt-4o-mini")
-     .AsIChatClient();
-
-AIAgent agent = new ChatClientAgent(
-    chatClient,
-    instructions: "You are a helpful assistant, you can help the user with weather information.",
-    tools: [AIFunctionFactory.Create(GetWeather)]);
-
-Console.WriteLine(await agent.RunAsync("What's the weather in Amsterdam?"));

dotnet/eng/MSBuild/LegacySupport.props

@@ -22,4 +22,12 @@
   <ItemGroup Condition="'$(InjectTrimAttributesOnLegacy)' == 'true' AND !$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\TrimAttributes\*.cs" LinkBase="LegacySupport\TrimAttributes" />
   </ItemGroup>
+
+  <ItemGroup Condition="'$(InjectRequiredMemberOnLegacy)' == 'true' AND !$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\RequiredMemberAttribute\*.cs" LinkBase="LegacySupport\RequiredMemberAttribute" />
+  </ItemGroup>
+
+  <ItemGroup Condition="'$(InjectCompilerFeatureRequiredOnLegacy)' == 'true' AND !$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\CompilerFeatureRequiredAttribute\*.cs" LinkBase="LegacySupport\CompilerFeatureRequiredAttribute" />
+  </ItemGroup>
 </Project>

dotnet/eng/MSBuild/Shared.props

@@ -8,4 +8,16 @@
   <ItemGroup Condition="'$(InjectSharedIntegrationTestCode)' == 'true'">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\IntegrationTests\*.cs" LinkBase="Shared\IntegrationTests" />
   </ItemGroup>
+  <ItemGroup Condition="'$(InjectSharedBuildTestCode)' == 'true'">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\CodeTests\*.cs" LinkBase="Shared\CodeTests" />
+  </ItemGroup>
+  <ItemGroup Condition="'$(InjectSharedWorkflowsExecution)' == 'true'">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\Workflows\Execution\*.cs" LinkBase="Shared\Workflows" />
+  </ItemGroup>
+  <ItemGroup Condition="'$(InjectSharedWorkflowsSettings)' == 'true'">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\Workflows\Settings\*.cs" LinkBase="Shared\Workflows" />
+  </ItemGroup>
+  <ItemGroup Condition="'$(InjectSharedFoundryAgents)' == 'true'">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\Foundry\Agents\*.cs" LinkBase="Shared\Foundry" />
+  </ItemGroup>
 </Project>

dotnet/nuget.config

@@ -2,6 +2,11 @@
 <configuration>
   <packageSources>
     <clear />
-    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />  
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
   </packageSources>
-</configuration>
+  <packageSourceMapping>
+    <packageSource key="nuget.org">
+      <package pattern="*" />
+    </packageSource>
+  </packageSourceMapping>
+</configuration>

dotnet/nuget/NUGET.md

@@ -1,10 +1,21 @@
 # About Microsoft Agent Framework
 
-To be filled in.
+Microsoft Agent Framework is a comprehensive .NET library for building, orchestrating, and deploying AI agents and multi-agent workflows. The framework provides everything from simple chat agents to complex multi-agent systems with graph-based orchestration capabilities.
+
+## Key Features
+
+- **Multi-Agent Orchestration**: Coordinate multiple agents using sequential, concurrent, group chat, and handoff patterns
+- **Graph-based Workflows**: Connect agents and functions with streaming, checkpointing, and human-in-the-loop capabilities, with both imperative or declarative workflow support
+- **Multiple Provider Support**: Seamlessly integrate with various LLM providers with more being added continuously
+- **Extensible Middleware**: Flexible request/response processing with custom pipelines and exception handling
+- **Built-in Observability**: OpenTelemetry integration for distributed tracing, monitoring, and debugging
+- **Cross-Platform**: Compatible with .NET 8.0, .NET Standard 2.0, and .NET Framework for broad deployment options
+
+Whether you're building simple AI assistants or complex multi-agent systems, Microsoft Agent Framework provides the tools and abstractions needed to create robust, scalable AI applications in .NET.
 
 # Getting Started ⚡
 
-- Learn more at the [documentation site](https://aka.ms/TBD).
-- Join the [Discord community](https://aka.ms/TBD).
-- Follow the team on [Semantic Kernel blog](https://aka.ms/TBD).
+- Learn more at the [documentation site](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview).
+- Join the [Discord community](https://discord.gg/b5zjErwbQM).
+- Follow the team on [Semantic Kernel blog](https://devblogs.microsoft.com/semantic-kernel/).
 - Check out the [GitHub repository](https://github.com/microsoft/agent-framework) for the latest updates.

dotnet/nuget/nuget-package.props

@@ -1,9 +1,10 @@
 <Project>
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
-    <VersionPrefix>0.0.1</VersionPrefix>
-    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix)</PackageVersion>
-    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)</PackageVersion>
+    <VersionPrefix>1.0.0</VersionPrefix>
+    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).251114.1</PackageVersion>
+    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.251114.1</PackageVersion>
+    <GitTag>1.0.0-preview.251114.1</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>
@@ -27,15 +28,15 @@
     <!-- Default description and tags. Packages can override. -->
     <Authors>Microsoft</Authors>
     <Company>Microsoft</Company>
-    <Product>Agent Framework</Product>
-    <Description>Empowers app owners to integrate Agents quickly and easily into their apps.</Description>
+    <Product>Microsoft Agent Framework</Product>
+    <Description>Microsoft Agent Framework is a comprehensive .NET library for building, orchestrating, and deploying AI agents and multi-agent workflows. The framework provides everything from simple chat agents to complex multi-agent systems with graph-based orchestration capabilities.</Description>
     <PackageTags>AI, Artificial Intelligence, Agent, SDK, Framework</PackageTags>
     <PackageId>$(AssemblyName)</PackageId>
 
     <!-- Required license, copyright, and repo information. Packages can override. -->
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <Copyright>© Microsoft Corporation. All rights reserved.</Copyright>
-    <PackageProjectUrl>https://aka.ms/tbd</PackageProjectUrl>
+    <PackageProjectUrl>https://learn.microsoft.com/agent-framework/</PackageProjectUrl>
     <RepositoryUrl>https://github.com/microsoft/agent-framework</RepositoryUrl>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
 

dotnet/samples/.editorconfig

@@ -1,8 +1,16 @@
 # Suppressing errors for Sample projects under dotnet/samples folder
 [*.cs]
-dotnet_diagnostic.CA2007.severity = none # Do not directly await a Task
-dotnet_diagnostic.CS1591.severity = none # Missing XML comment for publicly visible type or member
-dotnet_diagnostic.IDE1006.severity = warning # Naming rule violations
-dotnet_diagnostic.VSTHRD111.severity = none # Use .ConfigureAwait(bool) is hidden by default, set to none to prevent IDE from changing on autosave
 dotnet_diagnostic.CA1716.severity = none # Add summary to documentation comment.
 dotnet_diagnostic.CA2000.severity = none # Call System.IDisposable.Dispose on object before all references to it are out of scope
+dotnet_diagnostic.CA2007.severity = none # Do not directly await a Task
+
+dotnet_diagnostic.CS1591.severity = none # Missing XML comment for publicly visible type or member
+
+dotnet_diagnostic.IDE1006.severity = warning # Naming rule violations
+
+dotnet_diagnostic.VSTHRD111.severity = none # Use .ConfigureAwait(bool) is hidden by default, set to none to prevent IDE from changing on autosave
+dotnet_diagnostic.VSTHRD200.severity = none # Use Async suffix for async methods
+
+dotnet_diagnostic.MEAI001.severity = none   # [Experimental] APIs in Microsoft.Extensions.AI
+dotnet_diagnostic.OPENAI001.severity = none # [Experimental] APIs in OpenAI
+dotnet_diagnostic.SKEXP0110.severity = none # [Experimental] APIs in Microsoft.SemanticKernel

dotnet/samples/A2AClientServer/A2AClient/A2AClient.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <UserSecretsId>5ee045b0-aea3-4f08-8d31-32d1a6f8fed0</UserSecretsId>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="A2A" />
+    <PackageReference Include="System.CommandLine" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+    <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" VersionOverride="10.0.0-rc.2.25502.107" />
+    <PackageReference Include="System.Net.ServerSentEvents" VersionOverride="10.0.0-rc.2.25502.107" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.A2A\Microsoft.Agents.AI.A2A.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Abstractions\Microsoft.Agents.AI.Abstractions.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/A2AClientServer/A2AClient/HostClientAgent.cs

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+using System.ClientModel;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
+using OpenAI;
+
+namespace A2A;
+
+internal sealed class HostClientAgent
+{
+    internal HostClientAgent(ILoggerFactory loggerFactory)
+    {
+        this._logger = loggerFactory.CreateLogger("HostClientAgent");
+    }
+
+    internal async Task InitializeAgentAsync(string modelId, string apiKey, string[] agentUrls)
+    {
+        try
+        {
+            this._logger.LogInformation("Initializing Agent Framework agent with model: {ModelId}", modelId);
+
+            // Connect to the remote agents via A2A
+            var createAgentTasks = agentUrls.Select(CreateAgentAsync);
+            var agents = await Task.WhenAll(createAgentTasks);
+            var tools = agents.Select(agent => (AITool)agent.AsAIFunction()).ToList();
+
+            // Create the agent that uses the remote agents as tools
+            this.Agent = new OpenAIClient(new ApiKeyCredential(apiKey))
+             .GetChatClient(modelId)
+             .CreateAIAgent(instructions: "You specialize in handling queries for users and using your tools to provide answers.", name: "HostClient", tools: tools);
+        }
+        catch (Exception ex)
+        {
+            this._logger.LogError(ex, "Failed to initialize HostClientAgent");
+            throw;
+        }
+    }
+
+    /// <summary>
+    /// The associated <see cref="Agent"/>
+    /// </summary>
+    public AIAgent? Agent { get; private set; }
+
+    #region private
+    private readonly ILogger _logger;
+
+    private static async Task<AIAgent> CreateAgentAsync(string agentUri)
+    {
+        var url = new Uri(agentUri);
+        var httpClient = new HttpClient
+        {
+            Timeout = TimeSpan.FromSeconds(60)
+        };
+
+        var agentCardResolver = new A2ACardResolver(url, httpClient);
+
+        return await agentCardResolver.GetAIAgentAsync();
+    }
+    #endregion
+}

dotnet/samples/A2AClientServer/A2AClient/Program.cs

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.CommandLine;
+using System.Reflection;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Logging;
+
+namespace A2A;
+
+public static class Program
+{
+    public static async Task<int> Main(string[] args)
+    {
+        // Create root command with options
+        var rootCommand = new RootCommand("A2AClient");
+        rootCommand.SetAction((_, ct) => HandleCommandsAsync(ct));
+
+        // Run the command
+        return await rootCommand.Parse(args).InvokeAsync();
+    }
+
+    private static async Task HandleCommandsAsync(CancellationToken cancellationToken)
+    {
+        // Set up the logging
+        using var loggerFactory = LoggerFactory.Create(builder =>
+        {
+            builder.AddConsole();
+            builder.SetMinimumLevel(LogLevel.Information);
+        });
+        var logger = loggerFactory.CreateLogger("A2AClient");
+
+        // Retrieve configuration settings
+        IConfigurationRoot configRoot = new ConfigurationBuilder()
+            .AddEnvironmentVariables()
+            .AddUserSecrets(Assembly.GetExecutingAssembly())
+            .Build();
+        var apiKey = configRoot["A2AClient:ApiKey"] ?? throw new ArgumentException("A2AClient:ApiKey must be provided");
+        var modelId = configRoot["A2AClient:ModelId"] ?? "gpt-4.1";
+        var agentUrls = configRoot["A2AClient:AgentUrls"] ?? "http://localhost:5000/;http://localhost:5001/;http://localhost:5002/";
+
+        // Create the Host agent
+        var hostAgent = new HostClientAgent(loggerFactory);
+        await hostAgent.InitializeAgentAsync(modelId, apiKey, agentUrls!.Split(";"));
+        AgentThread thread = hostAgent.Agent!.GetNewThread();
+        try
+        {
+            while (true)
+            {
+                // Get user message
+                Console.Write("\nUser (:q or quit to exit): ");
+                string? message = Console.ReadLine();
+                if (string.IsNullOrWhiteSpace(message))
+                {
+                    Console.WriteLine("Request cannot be empty.");
+                    continue;
+                }
+
+                if (message is ":q" or "quit")
+                {
+                    break;
+                }
+
+                var agentResponse = await hostAgent.Agent!.RunAsync(message, thread, cancellationToken: cancellationToken);
+                foreach (var chatMessage in agentResponse.Messages)
+                {
+                    Console.ForegroundColor = ConsoleColor.Cyan;
+                    Console.WriteLine($"\nAgent: {chatMessage.Text}");
+                    Console.ResetColor();
+                }
+            }
+        }
+        catch (Exception ex)
+        {
+            logger.LogError(ex, "An error occurred while running the A2AClient");
+            return;
+        }
+    }
+}

dotnet/samples/A2AClientServer/A2AClient/README.md

@@ -0,0 +1,26 @@
+
+# A2A Client Sample
+Show how to create an A2A Client with a command line interface which invokes agents using the A2A protocol.
+
+## Run the Sample
+
+To run the sample, follow these steps:
+
+1. Run the A2A client:
+    ```bash
+    cd A2AClient
+    dotnet run
+    ```  
+2. Enter your request e.g. "Show me all invoices for Contoso?"
+
+## Set Environment Variables
+
+The agent urls are provided as a ` ` delimited list of strings
+
+```powershell
+cd dotnet/samples/A2AClientServer/A2AClient
+
+$env:OPENAI_MODEL="gpt-4o-mini"
+$env:OPENAI_API_KEY="<Your OPENAI api key>"
+$env:AGENT_URLS="http://localhost:5000/policy;http://localhost:5000/invoice;http://localhost:5000/logistics"
+```

dotnet/samples/A2AClientServer/A2AServer/A2AServer.csproj

@@ -0,0 +1,27 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <UserSecretsId>5ee045b0-aea3-4f08-8d31-32d1a6f8fed0</UserSecretsId>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Agents.Persistent" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" VersionOverride="10.0.0-rc.2.25502.107" />
+    <PackageReference Include="System.Net.ServerSentEvents" VersionOverride="10.0.0-rc.2.25502.107" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting.A2A.AspNetCore\Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting.A2A\Microsoft.Agents.AI.Hosting.A2A.csproj" />
+
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.A2A\Microsoft.Agents.AI.A2A.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/A2AClientServer/A2AServer/A2AServer.http

@@ -0,0 +1,85 @@
+### Each A2A agent is available at a different host address
+@hostInvoice = http://localhost:5000
+@hostPolicy = http://localhost:5001
+@hostLogistics = http://localhost:5002
+
+### Query agent card for the invoice agent
+GET {{hostInvoice}}/.well-known/agent-card.json
+
+### Send a message to the invoice agent
+POST {{hostInvoice}}
+Content-Type: application/json
+
+{
+    "id": "1",
+    "jsonrpc": "2.0",
+    "method": "message/send",
+    "params": {
+        "id": "12345",
+        "message": {
+            "kind": "message",
+            "role": "user",
+            "messageId": "msg_1",
+            "parts": [
+                {
+                    "kind": "text",
+                    "text": "Show me all invoices for Contoso?"
+                }
+            ]
+        }
+    }
+}
+
+### Query agent card for the policy agent
+GET {{hostPolicy}}/.well-known/agent-card.json
+
+### Send a message to the policy agent
+POST {{hostPolicy}}
+Content-Type: application/json
+
+{
+    "id": "1",
+    "jsonrpc": "2.0",
+    "method": "message/send",
+    "params": {
+        "id": "12345",
+        "message": {
+            "kind": "message",
+            "role": "user",
+            "messageId": "msg_1",
+            "parts": [
+                {
+                    "kind": "text",
+                    "text": "What is the policy for short shipments?"
+                }
+            ]
+        }
+    }
+}
+
+### Query agent card for the logistics agent
+GET {{hostLogistics}}/.well-known/agent-card.json
+
+### Send a message to the logistics agent
+POST {{hostLogistics}}
+Content-Type: application/json
+
+{
+    "id": "1",
+    "jsonrpc": "2.0",
+    "method": "message/send",
+    "params": {
+        "id": "12345",
+        "message": {
+            "kind": "message",
+            "role": "user",
+            "messageId": "msg_1",
+            "parts": [
+                {
+                    "kind": "text",
+                    "text": "What is the status for SHPMT-SAP-001?"
+                }
+            ]
+        }
+    }
+}

dotnet/samples/A2AClientServer/A2AServer/HostAgentFactory.cs

@@ -0,0 +1,147 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using A2A;
+using Azure.AI.Agents.Persistent;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI;
+
+namespace A2AServer;
+
+internal static class HostAgentFactory
+{
+    internal static async Task<(AIAgent, AgentCard)> CreateFoundryHostAgentAsync(string agentType, string model, string endpoint, string assistantId, IList<AITool>? tools = null)
+    {
+        var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
+        PersistentAgent persistentAgent = await persistentAgentsClient.Administration.GetAgentAsync(assistantId);
+
+        AIAgent agent = await persistentAgentsClient
+            .GetAIAgentAsync(persistentAgent.Id, chatOptions: new() { Tools = tools });
+
+        AgentCard agentCard = agentType.ToUpperInvariant() switch
+        {
+            "INVOICE" => GetInvoiceAgentCard(),
+            "POLICY" => GetPolicyAgentCard(),
+            "LOGISTICS" => GetLogisticsAgentCard(),
+            _ => throw new ArgumentException($"Unsupported agent type: {agentType}"),
+        };
+
+        return new(agent, agentCard);
+    }
+
+    internal static async Task<(AIAgent, AgentCard)> CreateChatCompletionHostAgentAsync(string agentType, string model, string apiKey, string name, string instructions, IList<AITool>? tools = null)
+    {
+        AIAgent agent = new OpenAIClient(apiKey)
+             .GetChatClient(model)
+             .CreateAIAgent(instructions, name, tools: tools);
+
+        AgentCard agentCard = agentType.ToUpperInvariant() switch
+        {
+            "INVOICE" => GetInvoiceAgentCard(),
+            "POLICY" => GetPolicyAgentCard(),
+            "LOGISTICS" => GetLogisticsAgentCard(),
+            _ => throw new ArgumentException($"Unsupported agent type: {agentType}"),
+        };
+
+        return new(agent, agentCard);
+    }
+
+    #region private
+    private static AgentCard GetInvoiceAgentCard()
+    {
+        var capabilities = new AgentCapabilities()
+        {
+            Streaming = false,
+            PushNotifications = false,
+        };
+
+        var invoiceQuery = new AgentSkill()
+        {
+            Id = "id_invoice_agent",
+            Name = "InvoiceQuery",
+            Description = "Handles requests relating to invoices.",
+            Tags = ["invoice", "semantic-kernel"],
+            Examples =
+            [
+                "List the latest invoices for Contoso.",
+            ],
+        };
+
+        return new()
+        {
+            Name = "InvoiceAgent",
+            Description = "Handles requests relating to invoices.",
+            Version = "1.0.0",
+            DefaultInputModes = ["text"],
+            DefaultOutputModes = ["text"],
+            Capabilities = capabilities,
+            Skills = [invoiceQuery],
+        };
+    }
+
+    private static AgentCard GetPolicyAgentCard()
+    {
+        var capabilities = new AgentCapabilities()
+        {
+            Streaming = false,
+            PushNotifications = false,
+        };
+
+        var policyQuery = new AgentSkill()
+        {
+            Id = "id_policy_agent",
+            Name = "PolicyAgent",
+            Description = "Handles requests relating to policies and customer communications.",
+            Tags = ["policy", "semantic-kernel"],
+            Examples =
+            [
+                "What is the policy for short shipments?",
+            ],
+        };
+
+        return new AgentCard()
+        {
+            Name = "PolicyAgent",
+            Description = "Handles requests relating to policies and customer communications.",
+            Version = "1.0.0",
+            DefaultInputModes = ["text"],
+            DefaultOutputModes = ["text"],
+            Capabilities = capabilities,
+            Skills = [policyQuery],
+        };
+    }
+
+    private static AgentCard GetLogisticsAgentCard()
+    {
+        var capabilities = new AgentCapabilities()
+        {
+            Streaming = false,
+            PushNotifications = false,
+        };
+
+        var logisticsQuery = new AgentSkill()
+        {
+            Id = "id_logistics_agent",
+            Name = "LogisticsQuery",
+            Description = "Handles requests relating to logistics.",
+            Tags = ["logistics", "semantic-kernel"],
+            Examples =
+            [
+                "What is the status for SHPMT-SAP-001",
+            ],
+        };
+
+        return new AgentCard()
+        {
+            Name = "LogisticsAgent",
+            Description = "Handles requests relating to logistics.",
+            Version = "1.0.0",
+            DefaultInputModes = ["text"],
+            DefaultOutputModes = ["text"],
+            Capabilities = capabilities,
+            Skills = [logisticsQuery],
+        };
+    }
+    #endregion
+}

dotnet/samples/A2AClientServer/A2AServer/Models/InvoiceQuery.cs

@@ -0,0 +1,167 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+
+namespace A2A;
+
+/// <summary>
+/// A simple invoice plugin that returns mock data.
+/// </summary>
+public class Product
+{
+    public string Name { get; set; }
+    public int Quantity { get; set; }
+    public decimal Price { get; set; } // Price per unit  
+
+    public Product(string name, int quantity, decimal price)
+    {
+        this.Name = name;
+        this.Quantity = quantity;
+        this.Price = price;
+    }
+
+    public decimal TotalPrice() => this.Quantity * this.Price; // Total price for this product  
+}
+
+public class Invoice
+{
+    public string TransactionId { get; set; }
+    public string InvoiceId { get; set; }
+    public string CompanyName { get; set; }
+    public DateTime InvoiceDate { get; set; }
+    public List<Product> Products { get; set; } // List of products  
+
+    public Invoice(string transactionId, string invoiceId, string companyName, DateTime invoiceDate, List<Product> products)
+    {
+        this.TransactionId = transactionId;
+        this.InvoiceId = invoiceId;
+        this.CompanyName = companyName;
+        this.InvoiceDate = invoiceDate;
+        this.Products = products;
+    }
+
+    public decimal TotalInvoicePrice() => this.Products.Sum(product => product.TotalPrice()); // Total price of all products in the invoice  
+}
+
+public class InvoiceQuery
+{
+    private readonly List<Invoice> _invoices;
+
+    public InvoiceQuery()
+    {
+        // Extended mock data with quantities and prices  
+        this._invoices =
+        [
+            new("TICKET-XYZ987", "INV789", "Contoso", GetRandomDateWithinLastTwoMonths(),
+            [
+                new("T-Shirts", 150, 10.00m),
+                new("Hats", 200, 15.00m),
+                new("Glasses", 300, 5.00m)
+            ]),
+            new("TICKET-XYZ111", "INV111", "XStore", GetRandomDateWithinLastTwoMonths(),
+            [
+                new("T-Shirts", 2500, 12.00m),
+                new("Hats", 1500, 8.00m),
+                new("Glasses", 200, 20.00m)
+            ]),
+            new("TICKET-XYZ222", "INV222",  "Cymbal Direct", GetRandomDateWithinLastTwoMonths(),
+            [
+                new("T-Shirts", 1200, 14.00m),
+                new("Hats", 800, 7.00m),
+                new("Glasses", 500, 25.00m)
+            ]),
+            new("TICKET-XYZ333", "INV333", "Contoso", GetRandomDateWithinLastTwoMonths(),
+            [
+                new("T-Shirts", 400, 11.00m),
+                new("Hats", 600, 15.00m),
+                new("Glasses", 700, 5.00m)
+            ]),
+            new("TICKET-XYZ444", "INV444", "XStore", GetRandomDateWithinLastTwoMonths(),
+            [
+                new("T-Shirts", 800, 10.00m),
+                new("Hats", 500, 18.00m),
+                new("Glasses", 300, 22.00m)
+            ]),
+            new("TICKET-XYZ555", "INV555", "Cymbal Direct", GetRandomDateWithinLastTwoMonths(),
+            [
+                new("T-Shirts", 1100, 9.00m),
+                new("Hats", 900, 12.00m),
+                new("Glasses", 1200, 15.00m)
+            ]),
+            new("TICKET-XYZ666", "INV666", "Contoso", GetRandomDateWithinLastTwoMonths(),
+            [
+                new("T-Shirts", 2500, 8.00m),
+                new("Hats", 1200, 10.00m),
+                new("Glasses", 1000, 6.00m)
+            ]),
+            new("TICKET-XYZ777", "INV777", "XStore", GetRandomDateWithinLastTwoMonths(),
+            [
+                new("T-Shirts", 1900, 13.00m),
+                new("Hats", 1300, 16.00m),
+                new("Glasses", 800, 19.00m)
+            ]),
+            new("TICKET-XYZ888", "INV888", "Cymbal Direct", GetRandomDateWithinLastTwoMonths(),
+            [
+                new("T-Shirts", 2200, 11.00m),
+                new("Hats", 1700, 8.50m),
+                new("Glasses", 600, 21.00m)
+            ]),
+            new("TICKET-XYZ999", "INV999", "Contoso", GetRandomDateWithinLastTwoMonths(),
+            [
+                new("T-Shirts", 1400, 10.50m),
+                new("Hats", 1100, 9.00m),
+                new("Glasses", 950, 12.00m)
+            ])
+        ];
+    }
+
+    public static DateTime GetRandomDateWithinLastTwoMonths()
+    {
+        // Get the current date and time  
+        DateTime endDate = DateTime.UtcNow;
+
+        // Calculate the start date, which is two months before the current date  
+        DateTime startDate = endDate.AddMonths(-2);
+
+        // Generate a random number of days between 0 and the total number of days in the range  
+        int totalDays = (endDate - startDate).Days;
+        int randomDays = Random.Shared.Next(0, totalDays + 1); // +1 to include the end date  
+
+        // Return the random date  
+        return startDate.AddDays(randomDays);
+    }
+
+    [Description("Retrieves invoices for the specified company and optionally within the specified time range")]
+    public IEnumerable<Invoice> QueryInvoices(string companyName, DateTime? startDate = null, DateTime? endDate = null)
+    {
+        var query = this._invoices.Where(i => i.CompanyName.Equals(companyName, StringComparison.OrdinalIgnoreCase));
+
+        if (startDate.HasValue)
+        {
+            query = query.Where(i => i.InvoiceDate >= startDate.Value);
+        }
+
+        if (endDate.HasValue)
+        {
+            query = query.Where(i => i.InvoiceDate <= endDate.Value);
+        }
+
+        return query.ToList();
+    }
+
+    [Description("Retrieves invoice using the transaction id")]
+    public IEnumerable<Invoice> QueryByTransactionId(string transactionId)
+    {
+        var query = this._invoices.Where(i => i.TransactionId.Equals(transactionId, StringComparison.OrdinalIgnoreCase));
+
+        return query.ToList();
+    }
+
+    [Description("Retrieves invoice using the invoice id")]
+    public IEnumerable<Invoice> QueryByInvoiceId(string invoiceId)
+    {
+        var query = this._invoices.Where(i => i.InvoiceId.Equals(invoiceId, StringComparison.OrdinalIgnoreCase));
+
+        return query.ToList();
+    }
+}

dotnet/samples/A2AClientServer/A2AServer/Program.cs

@@ -0,0 +1,113 @@
+// Copyright (c) Microsoft. All rights reserved.
+using A2A;
+using A2A.AspNetCore;
+using A2AServer;
+using Microsoft.Agents.AI;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+
+string agentId = string.Empty;
+string agentType = string.Empty;
+
+for (var i = 0; i < args.Length; i++)
+{
+    if (args[i].StartsWith("--agentId", StringComparison.InvariantCultureIgnoreCase) && i + 1 < args.Length)
+    {
+        agentId = args[++i];
+    }
+    else if (args[i].StartsWith("--agentType", StringComparison.InvariantCultureIgnoreCase) && i + 1 < args.Length)
+    {
+        agentType = args[++i];
+    }
+}
+
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddHttpClient().AddLogging();
+var app = builder.Build();
+
+var httpClient = app.Services.GetRequiredService<IHttpClientFactory>().CreateClient();
+var logger = app.Logger;
+
+IConfigurationRoot configuration = new ConfigurationBuilder()
+    .AddEnvironmentVariables()
+    .AddUserSecrets<Program>()
+    .Build();
+
+string? apiKey = configuration["OPENAI_API_KEY"];
+string model = configuration["OPENAI_MODEL"] ?? "gpt-4o-mini";
+string? endpoint = configuration["AZURE_FOUNDRY_PROJECT_ENDPOINT"];
+
+var invoiceQueryPlugin = new InvoiceQuery();
+IList<AITool> tools =
+    [
+    AIFunctionFactory.Create(invoiceQueryPlugin.QueryInvoices),
+    AIFunctionFactory.Create(invoiceQueryPlugin.QueryByTransactionId),
+    AIFunctionFactory.Create(invoiceQueryPlugin.QueryByInvoiceId)
+    ];
+
+AIAgent hostA2AAgent;
+AgentCard hostA2AAgentCard;
+
+if (!string.IsNullOrEmpty(endpoint) && !string.IsNullOrEmpty(agentId))
+{
+    (hostA2AAgent, hostA2AAgentCard) = agentType.ToUpperInvariant() switch
+    {
+        "INVOICE" => await HostAgentFactory.CreateFoundryHostAgentAsync(agentType, model, endpoint, agentId, tools),
+        "POLICY" => await HostAgentFactory.CreateFoundryHostAgentAsync(agentType, model, endpoint, agentId),
+        "LOGISTICS" => await HostAgentFactory.CreateFoundryHostAgentAsync(agentType, model, endpoint, agentId),
+        _ => throw new ArgumentException($"Unsupported agent type: {agentType}"),
+    };
+}
+else if (!string.IsNullOrEmpty(apiKey))
+{
+    (hostA2AAgent, hostA2AAgentCard) = agentType.ToUpperInvariant() switch
+    {
+        "INVOICE" => await HostAgentFactory.CreateChatCompletionHostAgentAsync(
+            agentType, model, apiKey, "InvoiceAgent",
+            """
+            You specialize in handling queries related to invoices.
+            """, tools),
+        "POLICY" => await HostAgentFactory.CreateChatCompletionHostAgentAsync(
+            agentType, model, apiKey, "PolicyAgent",
+            """
+            You specialize in handling queries related to policies and customer communications.
+            
+            Always reply with exactly this text:
+            
+            Policy: Short Shipment Dispute Handling Policy V2.1
+            
+            Summary: "For short shipments reported by customers, first verify internal shipment records
+            (SAP) and physical logistics scan data (BigQuery). If discrepancy is confirmed and logistics data
+            shows fewer items packed than invoiced, issue a credit for the missing items. Document the
+            resolution in SAP CRM and notify the customer via email within 2 business days, referencing the
+            original invoice and the credit memo number. Use the 'Formal Credit Notification' email
+            template."
+            """),
+        "LOGISTICS" => await HostAgentFactory.CreateChatCompletionHostAgentAsync(
+            agentType, model, apiKey, "LogisticsAgent",
+            """
+            You specialize in handling queries related to logistics.
+            
+            Always reply with exactly:
+            
+            Shipment number: SHPMT-SAP-001
+            Item: TSHIRT-RED-L
+            Quantity: 900
+            """),
+        _ => throw new ArgumentException($"Unsupported agent type: {agentType}"),
+    };
+}
+else
+{
+    throw new ArgumentException("Either A2AServer:ApiKey or A2AServer:ConnectionString & agentId must be provided");
+}
+
+var a2aTaskManager = app.MapA2A(
+    hostA2AAgent,
+    path: "/",
+    agentCard: hostA2AAgentCard,
+    taskManager => app.MapWellKnownAgentCard(taskManager, "/"));
+
+await app.RunAsync();

dotnet/samples/A2AClientServer/README.md

@@ -0,0 +1,235 @@
+# A2A Client and Server samples
+
+> **Warning**
+> The [A2A protocol](https://google.github.io/A2A/) is still under development and changing fast.
+> We will try to keep these samples updated as the protocol evolves.
+
+These samples are built with [official A2A C# SDK](https://www.nuget.org/packages/A2A) and demonstrates:
+
+1. Creating an A2A Server which makes an agent available via the A2A protocol.
+2. Creating an A2A Client with a command line interface which invokes agents using the A2A protocol.
+
+The demonstration has two components:
+
+1. `A2AServer` - You will run three instances of the server to correspond to three A2A servers each providing a single Agent i.e., the Invoice, Policy and Logistics agents.
+2. `A2AClient` - This represents a client application which will connect to the remote A2A servers using the A2A protocol so that it can use those agents when answering questions you will ask.
+
+<img src="./demo-architecture.png" alt="Demo Architecture"/>
+
+## Configuring Environment Variables
+
+The samples can be configured to use chat completion agents or Azure AI agents.
+
+### Configuring for use with Chat Completion Agents
+
+Provide your OpenAI API key via an environment variable
+
+```powershell
+$env:OPENAI_API_KEY="<Your OpenAI API Key>"
+```
+
+Use the following commands to run each A2A server:
+
+Execute the following command to build the sample:
+
+```powershell
+cd A2AServer
+dotnet build
+```
+
+```bash
+dotnet run --urls "http://localhost:5000;https://localhost:5010" --agentType "invoice" --no-build
+```
+
+```bash
+dotnet run --urls "http://localhost:5001;https://localhost:5011" --agentType "policy" --no-build
+```
+
+```bash
+dotnet run --urls "http://localhost:5002;https://localhost:5012" --agentType "logistics" --no-build
+```
+
+### Configuring for use with Azure AI Agents
+
+You must create the agents in an Azure AI Foundry project and then provide the project endpoint and agents ids. The instructions for each agent are as follows:
+
+- Invoice Agent
+    ```
+    You specialize in handling queries related to invoices.
+    ```
+- Policy Agent
+    ```
+    You specialize in handling queries related to policies and customer communications.
+
+    Always reply with exactly this text:
+
+    Policy: Short Shipment Dispute Handling Policy V2.1
+
+    Summary: "For short shipments reported by customers, first verify internal shipment records
+    (SAP) and physical logistics scan data (BigQuery). If discrepancy is confirmed and logistics data
+    shows fewer items packed than invoiced, issue a credit for the missing items. Document the
+    resolution in SAP CRM and notify the customer via email within 2 business days, referencing the
+    original invoice and the credit memo number. Use the 'Formal Credit Notification' email
+    template."
+    ```
+- Logistics Agent
+    ```
+    You specialize in handling queries related to logistics.
+
+    Always reply with exactly:
+
+        Shipment number: SHPMT-SAP-001
+        Item: TSHIRT-RED-L
+        Quantity: 900"
+    ```
+
+```powershell
+$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://ai-foundry-your-project.services.ai.azure.com/api/projects/ai-proj-ga-your-project" # Replace with your Foundry Project endpoint
+```
+
+Use the following commands to run each A2A server
+
+```bash
+dotnet run --urls "http://localhost:5000;https://localhost:5010" --agentId "<Invoice Agent Id>" --agentType "invoice" --no-build
+```
+
+```bash
+dotnet run --urls "http://localhost:5001;https://localhost:5011" --agentId "<Policy Agent Id>" --agentType "policy" --no-build
+```
+
+```bash
+dotnet run --urls "http://localhost:5002;https://localhost:5012" --agentId "<Logistics Agent Id>" --agentType "logistics" --no-build
+```
+
+### Testing the Agents using the Rest Client
+
+This sample contains a [.http file](https://learn.microsoft.com/aspnet/core/test/http-files?view=aspnetcore-9.0) which can be used to test the agent.
+
+1. In Visual Studio open [./A2AServer/A2AServer.http](./A2AServer/A2AServer.http)
+1. There are two sent requests for each agent, e.g., for the invoice agent:
+    1. Query agent card for the invoice agent
+        `GET {{hostInvoice}}/.well-known/agent-card.json`
+    1. Send a message to the invoice agent
+        ```
+        POST {{hostInvoice}}
+        Content-Type: application/json
+
+        {
+            "id": "1",
+            "jsonrpc": "2.0",
+            "method": "message/send",
+            "params": {
+                "id": "12345",
+                "message": {
+                    "kind": "message",
+                    "role": "user",
+                    "messageId": "msg_1",
+                    "parts": [
+                        {
+                            "kind": "text",
+                            "text": "Show me all invoices for Contoso?"
+                        }
+                    ]
+                }
+            }
+        }
+        ```
+
+Sample output from the request to display the agent card:
+
+<img src="./rest-client-agent-card.png" alt="Agent Card"/>
+
+Sample output from the request to send a message to the agent via A2A protocol:
+
+<img src="./rest-client-send-message.png" alt="Send Message"/>
+
+### Testing the Agents using the A2A Inspector
+
+The A2A Inspector is a web-based tool designed to help developers inspect, debug, and validate servers that implement the Google A2A (Agent2Agent) protocol. It provides a user-friendly interface to interact with an A2A agent, view communication, and ensure specification compliance.
+
+For more information go [here](https://github.com/a2aproject/a2a-inspector).
+
+Running the [inspector with Docker](https://github.com/a2aproject/a2a-inspector?tab=readme-ov-file#option-two-run-with-docker) is the easiest way to get started.
+
+1. Navigate to the A2A Inspector in your browser: [http://127.0.0.1:8080/](http://127.0.0.1:8080/)
+1. Enter the URL of the Agent you are running e.g., [http://host.docker.internal:5000](http://host.docker.internal:5000)
+1. Connect to the agent and the agent card will be displayed and validated.
+1. Type a message and send it to the agent using A2A protocol.
+    1. The response will be validated automatically and then displayed in the UI.
+    1. You can select the response to view the raw json.
+
+Agent card after connecting to an agent using the A2A protocol:
+
+<img src="./a2a-inspector-agent-card.png" alt="Agent Card"/>
+
+Sample response after sending a message to the agent via A2A protocol:
+
+<img src="./a2a-inspector-send-message.png" alt="Send Message"/>
+
+Raw JSON response from an A2A agent:
+
+<img src="./a2a-inspector-raw-json-response.png" alt="Response Raw JSON"/>
+
+### Configuring Agents for the A2A Client
+
+The A2A client will connect to remote agents using the A2A protocol.
+
+By default the client will connect to the invoice, policy and logistics agents provided by the sample A2A Server.
+
+These are available at the following URL's:
+
+- Invoice Agent: http://localhost:5000/ 
+- Policy Agent: http://localhost:5001/ 
+- Logistics Agent: http://localhost:5002/
+
+If you want to change which agents are using then set the agents url as a space delimited string as follows:
+
+```powershell
+$env:A2A_AGENT_URLS="http://localhost:5000/;http://localhost:5001/;http://localhost:5002/"
+```
+
+## Run the Sample
+
+To run the sample, follow these steps:
+
+1. Run the A2A server's using the commands shown earlier
+2. Run the A2A client:
+    ```bash
+    cd A2AClient
+    dotnet run
+    ```  
+3. Enter your request e.g. "Customer is disputing transaction TICKET-XYZ987 as they claim the received fewer t-shirts than ordered."
+4. The host client agent will call the remote agents, these calls will be displayed as console output. The final answer will use information from the remote agents. The sample below includes all three agents but in your case you may only see the policy and invoice agent.
+
+Sample output from the A2A client:
+
+```
+A2AClient> dotnet run
+info: HostClientAgent[0]
+      Initializing Agent Framework agent with model: gpt-4o-mini
+
+User (:q or quit to exit): Customer is disputing transaction TICKET-XYZ987 as they claim the received fewer t-shirts than ordered.
+
+Agent:
+
+Agent:
+
+Agent: The transaction details for **TICKET-XYZ987** are as follows:
+
+- **Invoice ID:** INV789
+- **Company Name:** Contoso
+- **Invoice Date:** September 4, 2025
+- **Products:**
+  - **T-Shirts:** 150 units at $10.00 each
+  - **Hats:** 200 units at $15.00 each
+  - **Glasses:** 300 units at $5.00 each
+
+To proceed with the dispute regarding the quantity of t-shirts delivered, please specify the exact quantity issue � how many t-shirts were actually received compared to the ordered amount.
+
+### Customer Service Policy for Handling Disputes
+**Short Shipment Dispute Handling Policy V2.1**
+- **Summary:** For short shipments reported by customers, first verify internal shipment records and physical logistics scan data. If a discrepancy is confirmed and the logistics data shows fewer items were packed than invoiced, a credit for the missing items will be issued.
+- **Follow-up Actions:** Document the resolution in the SAP CRM and notify the customer via email within 2 business days, referencing the original invoice and the credit memo number, using the 'Formal Credit Notification' email template.
+
+Please provide me with the information regarding the specific quantity issue so I can assist you further.
+```

dotnet/samples/AGUIClientServer/AGUIClient/AGUIClient.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <UserSecretsId>a8b2e9f0-1ea3-4f18-9d41-42d1a6f8fe10</UserSecretsId>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="System.CommandLine" />
+    <PackageReference Include="Microsoft.Extensions.Hosting" />
+    <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" VersionOverride="10.0.0-rc.2.25502.107" />
+    <PackageReference Include="System.Net.ServerSentEvents" VersionOverride="10.0.0-rc.2.25502.107" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.AGUI\Microsoft.Agents.AI.AGUI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/AGUIClientServer/AGUIClient/AGUIClientSerializerContext.cs

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use the AG-UI client to connect to a remote AG-UI server
+// and display streaming updates including conversation/response metadata, text content, and errors.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIClient;
+
+[JsonSerializable(typeof(SensorRequest))]
+[JsonSerializable(typeof(SensorResponse))]
+internal sealed partial class AGUIClientSerializerContext : JsonSerializerContext;

dotnet/samples/AGUIClientServer/AGUIClient/Program.cs

@@ -0,0 +1,213 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use the AG-UI client to connect to a remote AG-UI server
+// and display streaming updates including conversation/response metadata, text content, and errors.
+
+using System.CommandLine;
+using System.ComponentModel;
+using System.Reflection;
+using System.Text;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.AGUI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Logging;
+
+namespace AGUIClient;
+
+public static class Program
+{
+    public static async Task<int> Main(string[] args)
+    {
+        // Create root command with options
+        RootCommand rootCommand = new("AGUIClient");
+        rootCommand.SetAction((_, ct) => HandleCommandsAsync(ct));
+
+        // Run the command
+        return await rootCommand.Parse(args).InvokeAsync();
+    }
+
+    private static async Task HandleCommandsAsync(CancellationToken cancellationToken)
+    {
+        // Set up the logging
+        using ILoggerFactory loggerFactory = LoggerFactory.Create(builder =>
+        {
+            builder.AddConsole();
+            builder.SetMinimumLevel(LogLevel.Information);
+        });
+        ILogger logger = loggerFactory.CreateLogger("AGUIClient");
+
+        // Retrieve configuration settings
+        IConfigurationRoot configRoot = new ConfigurationBuilder()
+            .AddEnvironmentVariables()
+            .AddUserSecrets(Assembly.GetExecutingAssembly())
+            .Build();
+
+        string serverUrl = configRoot["AGUI_SERVER_URL"] ?? "http://localhost:5100";
+
+        logger.LogInformation("Connecting to AG-UI server at: {ServerUrl}", serverUrl);
+
+        // Create the AG-UI client agent
+        using HttpClient httpClient = new()
+        {
+            Timeout = TimeSpan.FromSeconds(60)
+        };
+
+        var changeBackground = AIFunctionFactory.Create(
+            () =>
+            {
+                Console.ForegroundColor = ConsoleColor.DarkBlue;
+                Console.WriteLine("Changing color to blue");
+            },
+            name: "change_background_color",
+            description: "Change the console background color to dark blue."
+        );
+
+        var readClientClimateSensors = AIFunctionFactory.Create(
+            ([Description("The sensors measurements to include in the response")] SensorRequest request) =>
+            {
+                return new SensorResponse()
+                {
+                    Temperature = 22.5,
+                    Humidity = 45.0,
+                    AirQualityIndex = 75
+                };
+            },
+            name: "read_client_climate_sensors",
+            description: "Reads the climate sensor data from the client device.",
+            serializerOptions: AGUIClientSerializerContext.Default.Options
+        );
+
+        var chatClient = new AGUIChatClient(
+            httpClient,
+            serverUrl,
+            jsonSerializerOptions: AGUIClientSerializerContext.Default.Options);
+
+        AIAgent agent = chatClient.CreateAIAgent(
+            name: "agui-client",
+            description: "AG-UI Client Agent",
+            tools: [changeBackground, readClientClimateSensors]);
+
+        AgentThread thread = agent.GetNewThread();
+        List<ChatMessage> messages = [new(ChatRole.System, "You are a helpful assistant.")];
+        try
+        {
+            while (true)
+            {
+                // Get user message
+                Console.Write("\nUser (:q or quit to exit): ");
+                string? message = Console.ReadLine();
+                if (string.IsNullOrWhiteSpace(message))
+                {
+                    Console.WriteLine("Request cannot be empty.");
+                    continue;
+                }
+
+                if (message is ":q" or "quit")
+                {
+                    break;
+                }
+
+                messages.Add(new(ChatRole.User, message));
+
+                // Call RunStreamingAsync to get streaming updates
+                bool isFirstUpdate = true;
+                string? threadId = null;
+                var updates = new List<ChatResponseUpdate>();
+                await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(messages, thread, cancellationToken: cancellationToken))
+                {
+                    // Use AsChatResponseUpdate to access ChatResponseUpdate properties
+                    ChatResponseUpdate chatUpdate = update.AsChatResponseUpdate();
+                    updates.Add(chatUpdate);
+                    if (chatUpdate.ConversationId != null)
+                    {
+                        threadId = chatUpdate.ConversationId;
+                    }
+
+                    // Display run started information from the first update
+                    if (isFirstUpdate && threadId != null && update.ResponseId != null)
+                    {
+                        Console.ForegroundColor = ConsoleColor.Yellow;
+                        Console.WriteLine($"\n[Run Started - Thread: {threadId}, Run: {update.ResponseId}]");
+                        Console.ResetColor();
+                        isFirstUpdate = false;
+                    }
+
+                    // Display different content types with appropriate formatting
+                    foreach (AIContent content in update.Contents)
+                    {
+                        switch (content)
+                        {
+                            case TextContent textContent:
+                                Console.ForegroundColor = ConsoleColor.Cyan;
+                                Console.Write(textContent.Text);
+                                Console.ResetColor();
+                                break;
+
+                            case FunctionCallContent functionCallContent:
+                                Console.ForegroundColor = ConsoleColor.Green;
+                                Console.WriteLine($"\n[Function Call - Name: {functionCallContent.Name}, Arguments: {PrintArguments(functionCallContent.Arguments)}]");
+                                Console.ResetColor();
+                                break;
+
+                            case FunctionResultContent functionResultContent:
+                                Console.ForegroundColor = ConsoleColor.Magenta;
+                                if (functionResultContent.Exception != null)
+                                {
+                                    Console.WriteLine($"\n[Function Result - Exception: {functionResultContent.Exception}]");
+                                }
+                                else
+                                {
+                                    Console.WriteLine($"\n[Function Result - Result: {functionResultContent.Result}]");
+                                }
+                                Console.ResetColor();
+                                break;
+
+                            case ErrorContent errorContent:
+                                Console.ForegroundColor = ConsoleColor.Red;
+                                string code = errorContent.AdditionalProperties?["Code"] as string ?? "Unknown";
+                                Console.WriteLine($"\n[Error - Code: {code}, Message: {errorContent.Message}]");
+                                Console.ResetColor();
+                                break;
+                        }
+                    }
+                }
+                if (updates.Count > 0 && !updates[^1].Contents.Any(c => c is TextContent))
+                {
+                    var lastUpdate = updates[^1];
+                    Console.ForegroundColor = ConsoleColor.Yellow;
+                    Console.WriteLine();
+                    Console.WriteLine($"[Run Ended - Thread: {threadId}, Run: {lastUpdate.ResponseId}]");
+                    Console.ResetColor();
+                }
+                messages.Clear();
+                Console.WriteLine();
+            }
+        }
+        catch (OperationCanceledException)
+        {
+            logger.LogInformation("AGUIClient operation was canceled.");
+        }
+        catch (Exception ex) when (ex is not OutOfMemoryException and not StackOverflowException and not ThreadAbortException and not AccessViolationException)
+        {
+            logger.LogError(ex, "An error occurred while running the AGUIClient");
+            return;
+        }
+    }
+
+    private static string PrintArguments(IDictionary<string, object?>? arguments)
+    {
+        if (arguments == null)
+        {
+            return "";
+        }
+        var builder = new StringBuilder();
+        builder.AppendLine();
+        foreach (var kvp in arguments)
+        {
+            builder.AppendLine($"   Name: {kvp.Key}");
+            builder.AppendLine($"   Value: {kvp.Value}");
+        }
+        return builder.ToString();
+    }
+}