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.11
+        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

@@ -18,7 +18,7 @@ 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:
@@ -27,16 +27,18 @@ jobs:
     env:
       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-file: "python/pyproject.toml"
-          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
+          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
@@ -46,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,6 +17,7 @@ env:
   # Configure a constant location for the uv cache
   UV_CACHE_DIR: /tmp/.uv-cache
   RUN_INTEGRATION_TESTS: "true"
+  RUN_SAMPLES_TESTS: ${{ vars.RUN_SAMPLES_TESTS }}
 
 jobs:
   paths-filter:
@@ -27,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:
@@ -42,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 }}
@@ -57,78 +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-file: "python/pyproject.toml"
-          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_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ secrets.AZUREOPENAI__ENDPOINT }}
-      PACKAGE_NAME: "azure"
+      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-file: "python/pyproject.toml"
-          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-file: "python/pyproject.toml"
-          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

@@ -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-file: "python/pyproject.toml"
-          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

@@ -19,9 +19,9 @@ jobs:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Download coverage report
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v6
         with:
           github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
           run-id: ${{ github.event.workflow_run.id }}
@@ -39,7 +39,7 @@ jobs:
           echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
       - name: Pytest coverage comment
         id: coverageComment
-        uses: MishaKav/pytest-coverage-comment@v1.1.53
+        uses: MishaKav/pytest-coverage-comment@v1.1.59
         with:
           github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
           issue-number: ${{ env.PR_NUMBER }}

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

@@ -20,25 +20,25 @@ jobs:
     env:
       UV_PYTHON: "3.10"
     steps:
-      - uses: actions/checkout@v4
+      - 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 uv
-        uses: astral-sh/setup-uv@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
         with:
-          version-file: "python/pyproject.toml"
-          enable-cache: true
-          cache-suffix: ${{ runner.os }}-${{ env.UV_PYTHON }}
-          cache-dependency-glob: "**/uv.lock"
-      - name: Install the project
-        run: uv sync --all-extras --dev
+          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-report=xml:python-coverage.xml -q --junitxml=pytest.xml
+        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@v4
+        uses: actions/upload-artifact@v5
         with:
           path: |
             python/python-coverage.xml

.github/workflows/python-tests.yml

@@ -16,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:
@@ -26,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-file: "python/pyproject.toml"
-          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
@@ -107,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/
@@ -196,3 +198,29 @@ 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,31 +1,179 @@
-# 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!
 
-Below are the basics for each language implementation. For more details on python see [here](./python/README.md) and for .NET see [here](./dotnet/README.md).
+[![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 --pre
+# This will install all sub-packages, see `python/packages` for individual packages.
+# It may take a minute on first install on Windows.
+```
+
+.NET
+
+```bash
+dotnet add package Microsoft.Agents.AI
+```
+
+### 📚 Documentation
+
+- **[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
+
+### ✨ **Highlights**
+
+- **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, human-in-the-loop, and time-travel capabilities
+  - [Python workflows](./python/samples/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/)
+
+<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>
+
+- **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.azure import AzureOpenAIResponsesClient
+from azure.identity import AzureCliCredential
+
+
+async def main():
+    # 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.",
+    )
+
+    print(await agent.run("Write a haiku about Microsoft Agent Framework."))
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Basic Agent - .NET
+
+Create a simple Agent, using OpenAI Responses, that writes a haiku about the Microsoft Agent Framework
+
+```c#
+// dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
+using System;
+using OpenAI;
+
+// 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.");
+
+Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
+```
+
+Create a simple Agent, using Azure OpenAI Responses with token based auth, that writes a haiku about the Microsoft Agent Framework
+
+```c#
+// dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
+// dotnet add package Azure.Identity
+// Use `az login` to authenticate with Azure CLI
+using System;
+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
 
 ### Python
-- [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
-- [Azure Integration](./python/packages/azure): Azure OpenAI and AI Foundry integration
 
-### .Net
-- [Getting Started with Agents](./dotnet/samples/GettingStarted/Steps): Basic agent creation and tool usage
-- [Agent Provider Samples](./dotnet/samples/GettingStarted/Providers): Samples showing different agent providers
-- [Orchestration Samples](./dotnet/samples/GettingStarted/Orchestration): Advanced multi-agent patterns
+- [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 Documentation
+### .NET
 
-- [Agent Framework Repository](https://github.com/microsoft/agent-framework)
+- [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)
-- Learn docs are coming soon.
+
+## 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

@@ -23,23 +23,23 @@ To download nightly builds follow the following steps:
     <configuration>
       <packageSources>
         <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
-        <add key="github" value="https://nuget.pkg.github.com/microsoft/index.json" />
+        <add key="GitHubMicrosoft" value="https://nuget.pkg.github.com/microsoft/index.json" />
       </packageSources>
     
       <packageSourceMapping>
         <packageSource key="nuget.org">
           <package pattern="*" />
         </packageSource>
-        <packageSource key="github">
+        <packageSource key="GitHubMicrosoft">
           <package pattern="*nightly"/>
         </packageSource>
       </packageSourceMapping>
     
       <packageSourceCredentials>
-        <github>
-            <add key="Username" value="<Your GitHub Id>" />
-            <add key="ClearTextPassword" value="<Your Personal Access Token>" />
-          </github>
+        <GitHubMicrosoft>
+          <add key="Username" value="<Your GitHub Id>" />
+          <add key="ClearTextPassword" value="<Your Personal Access Token>" />
+        </GitHubMicrosoft>
       </packageSourceCredentials>
     </configuration>
     ```
@@ -47,8 +47,8 @@ To download nightly builds follow the following steps:
     * 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.Extensions.AI.Agents --version 0.0.1-nightly-250731.6-alpha`
+    * 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.Extensions.AI.Agents" Version="*-*" />`
+    * `<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/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/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,44 +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.IDE0079.severity = none # Remove unnecessary suppression
 dotnet_diagnostic.IDE0290.severity = none # Use primary constructor
-dotnet_diagnostic.IDE0046.severity = none # if statement can be simplified
-dotnet_diagnostic.IDE0057.severity = none # Substring can be simplified
-dotnet_diagnostic.IDE0042.severity = none # Variable declaration can be deconstructed
-dotnet_diagnostic.IDE0047.severity = none # Parentheses can be removed
-
-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.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
@@ -436,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,11 +6,12 @@
     <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>
@@ -32,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,69 +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.4.0" />
-    <PackageVersion Include="Aspire.Hosting.Azure.CognitiveServices" Version="9.4.0" />
-    <PackageVersion Include="Aspire.Hosting.Azure.CosmosDB" Version="9.4.0" />
-    <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="9.3.1" />
-    <PackageVersion Include="Aspire.Hosting.Testing" 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.AspNetCore.OpenApi" Version="9.0.7" />
-    <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="Microsoft.Azure.Cosmos" Version="3.52.0" />
-    <!-- Newtonsoft (Required by CosmosClient) -->
-    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
-    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="9.0.3" />
+    <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.Net.ServerSentEvents" Version="9.0.7" />
-    <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.Bcl.AsyncInterfaces" Version="9.0.7" />
-    <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.61.0-preview" />
+    <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" />
@@ -77,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>
@@ -93,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>
@@ -114,4 +169,4 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
-</Project>
+</Project>

dotnet/README.md

@@ -1,64 +1,41 @@
 # Get Started with Microsoft Agent Framework for C# Developers
 
-## Run the Minimal Console demo
+## Samples
 
-The Minimal Console demo is a simple console application which shows how to create and run an agent.
+- [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
 
-Supported Platforms:
-- .Net: net9.0, net8.0, netstandard2.0, net472 
-- OS: Windows, macOS, Linux
+## Quickstart
 
-If you want to use the latest published packages following the instructions [here](../docs/FAQS.md).
+### Basic Agent - .NET
 
-### 1. Configure required environment variables
+```c#
+using System;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
 
-This samples uses Azure OpenAI by default so you need to set the following environment variable
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")!;
 
-``` powershell
-$env:AZURE_OPENAI_ENDPOINT = "https://<your deployment>.openai.azure.com/"
+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."));
 ```
 
-If you want to use OpenAI
+## Examples & Samples
 
-1. Edit [Program.cs](./demos/MinimalConsole/Program.cs) and change the following lines:
-    ```csharp
-    AIAgent agent = new AzureOpenAIClient(
-      new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!),
-      new AzureCliCredential())
-       .GetChatClient("gpt-4o-mini")
-       .CreateAIAgent(
-         instructions: "You are a helpful assistant, you can help the user with weather information.",
-         tools: [AIFunctionFactory.Create(GetWeather)]);
-    ```
-    To this:
-    ```csharp
-    AIAgent agent = new OpenAIClient(Environment.GetEnvironmentVariable("OPENAI_API_KEY")!)
-      .GetChatClient("gpt-4o-mini")
-      .CreateAIAgent(
-        instructions: "You are a helpful assistant, you can help the user with weather information.",
-        tools: [AIFunctionFactory.Create(GetWeather)]);
-    ```
-2. Create an environment variable with your OpenAI key 
-    ``` powershell
-    $env:OPENAI_API_KEY = "sk-..."
-    ```
+- [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
 
-### 2. Build the project
-
-```powershell
-cd demos\MinimalConsole
-dotnet build
-```
-
-### 3. Run the demonstration
-
-``` powershell
-dotnet run --framework net9.0 --no-build
-```
-
-Sample output:
-
-```
-The weather in Amsterdam is currently cloudy, with a high temperature of 15°C.
-```
+## 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,19 +4,13 @@
     <BuildType Name="Publish" />
     <BuildType Name="Release" />
   </Configurations>
-  <Folder Name="/ConformanceTests/">
-    <Project Path="tests/AgentConformance.IntegrationTests/AgentConformance.IntegrationTests.csproj" />
-    <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
-    <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.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="/Demos/">
-    <Project Path="demos/MinimalConsole/MinimalConsole.csproj" />
-  </Folder>
   <Folder Name="/Samples/">
-    <Project Path="samples/GettingStarted/GettingStarted.csproj" />
+    <File Path="samples/README.md" />
+  </Folder>
+  <Folder Name="/Samples/A2AClientServer/">
+    <File Path="samples/A2AClientServer/README.md" />
+    <Project Path="samples/A2AClientServer/A2AClient/A2AClient.csproj" />
+    <Project Path="samples/A2AClientServer/A2AServer/A2AServer.csproj" />
   </Folder>
   <Folder Name="/Samples/AgentWebChat/">
     <Project Path="samples/AgentWebChat/AgentWebChat.AgentHost/AgentWebChat.AgentHost.csproj" />
@@ -24,33 +18,233 @@
     <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" />
     <File Path=".gitignore" />
     <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" />
@@ -61,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" />
@@ -90,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" />
@@ -106,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" />
@@ -114,25 +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.Hosting/Microsoft.Extensions.AI.Agents.Hosting.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.Storage.CosmosDB/Microsoft.Extensions.AI.Agents.Runtime.Storage.CosmosDB.csproj" />
-    <Project Path="src/Microsoft.Extensions.AI.Agents.Runtime/Microsoft.Extensions.AI.Agents.Runtime.csproj" />
-    <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" />
-    <Project Path="tests/Microsoft.Extensions.AI.Agents.Abstractions.UnitTests/Microsoft.Extensions.AI.Agents.Abstractions.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Extensions.AI.Agents.Hosting.UnitTests/Microsoft.Extensions.AI.Agents.Hosting.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Extensions.AI.Agents.Runtime.Abstractions.UnitTests/Microsoft.Extensions.AI.Agents.Runtime.Abstractions.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Extensions.AI.Agents.UnitTests/Microsoft.Extensions.AI.Agents.UnitTests.csproj" />
-    <Project Path="tests/CosmosDB.IntegrationTests/Microsoft.Extensions.AI.Agents.Runtime.Storage.CosmosDB.Tests.AppHost/Microsoft.Extensions.AI.Agents.Runtime.Storage.CosmosDB.Tests.AppHost.csproj" />
-    <Project Path="tests/CosmosDB.IntegrationTests/Microsoft.Extensions.AI.Agents.Runtime.Storage.CosmosDB.Tests/Microsoft.Extensions.AI.Agents.Runtime.Storage.CosmosDB.Tests.csproj" />
+  <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/MinimalConsole.csproj

@@ -1,20 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFrameworks>$(ProjectsTargetFrameworks)</TargetFrameworks>
-    <TargetFrameworks Condition="'$(Configuration)' == 'Debug'">$(ProjectsDebugTargetFrameworks)</TargetFrameworks>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
-    <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\src\Microsoft.Extensions.AI.Agents.OpenAI\Microsoft.Extensions.AI.Agents.OpenAI.csproj" />
-    <ProjectReference Include="..\..\src\Microsoft.Extensions.AI.Agents\Microsoft.Extensions.AI.Agents.csproj" />
-  </ItemGroup>
-
-</Project>

dotnet/demos/MinimalConsole/Program.cs

@@ -1,23 +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;
-using OpenAI;
-
-[Description("Get the weather for a given location.")]
-static string GetWeather([Description("The location to get the weather for.")] string location)
-    => $"The weather in {location} is cloudy with a high of 15°C.";
-
-AIAgent agent = new AzureOpenAIClient(
-    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!),
-    new AzureCliCredential())
-     .GetChatClient("gpt-4o-mini")
-     .CreateAIAgent(
-        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();
+    }
+}

dotnet/samples/AGUIClientServer/AGUIClient/README.md

@@ -0,0 +1,34 @@
+# AG-UI Client
+
+This is a console application that demonstrates how to connect to an AG-UI server and interact with remote agents using the AG-UI protocol.
+
+## Features
+
+- Connects to an AG-UI server endpoint
+- Displays streaming updates with color-coded output:
+  - **Yellow**: Run started notifications
+  - **Cyan**: Agent text responses (streamed)
+  - **Green**: Run finished notifications
+  - **Red**: Error messages (if any)
+- Interactive prompt loop for sending messages
+
+## Configuration
+
+Set the following environment variable to specify the AG-UI server URL:
+
+```powershell
+$env:AGUI_SERVER_URL="http://localhost:5100"
+```
+
+If not set, the default is `http://localhost:5100`.
+
+## Running the Client
+
+1. Make sure the AG-UI server is running
+2. Run the client:
+   ```bash
+   cd AGUIClient
+   dotnet run
+   ```
+3. Enter your messages and observe the streaming updates
+4. Type `:q` or `quit` to exit

dotnet/samples/AGUIClientServer/AGUIClient/SensorRequest.cs

@@ -0,0 +1,13 @@
+// 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.
+
+namespace AGUIClient;
+
+internal sealed class SensorRequest
+{
+    public bool IncludeTemperature { get; set; } = true;
+    public bool IncludeHumidity { get; set; } = true;
+    public bool IncludeAirQualityIndex { get; set; } = true;
+}

dotnet/samples/AGUIClientServer/AGUIClient/SensorResponse.cs

@@ -0,0 +1,13 @@
+// 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.
+
+namespace AGUIClient;
+
+internal sealed class SensorResponse
+{
+    public double Temperature { get; set; }
+    public double Humidity { get; set; }
+    public int AirQualityIndex { get; set; }
+}

dotnet/samples/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <UserSecretsId>b9c3f1e1-2fb4-5g29-0e52-53e2b7g9gf21</UserSecretsId>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <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.AGUI.AspNetCore\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.AGUI\Microsoft.Agents.AI.AGUI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/AGUIClientServer/AGUIDojoServer/AGUIDojoServerSerializerContext.cs

@@ -0,0 +1,11 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer;
+
+[JsonSerializable(typeof(WeatherInfo))]
+[JsonSerializable(typeof(Recipe))]
+[JsonSerializable(typeof(Ingredient))]
+[JsonSerializable(typeof(RecipeResponse))]
+internal sealed partial class AGUIDojoServerSerializerContext : JsonSerializerContext;

dotnet/samples/AGUIClientServer/AGUIDojoServer/ChatClientAgentFactory.cs

@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using ChatClient = OpenAI.Chat.ChatClient;
+
+namespace AGUIDojoServer;
+
+internal static class ChatClientAgentFactory
+{
+    private static AzureOpenAIClient? s_azureOpenAIClient;
+    private static string? s_deploymentName;
+
+    public static void Initialize(IConfiguration configuration)
+    {
+        string endpoint = configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+        s_deploymentName = configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
+
+        s_azureOpenAIClient = new AzureOpenAIClient(
+            new Uri(endpoint),
+            new DefaultAzureCredential());
+    }
+
+    public static ChatClientAgent CreateAgenticChat()
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        return chatClient.AsIChatClient().CreateAIAgent(
+            name: "AgenticChat",
+            description: "A simple chat agent using Azure OpenAI");
+    }
+
+    public static ChatClientAgent CreateBackendToolRendering()
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        return chatClient.AsIChatClient().CreateAIAgent(
+            name: "BackendToolRenderer",
+            description: "An agent that can render backend tools using Azure OpenAI",
+            tools: [AIFunctionFactory.Create(
+                GetWeather,
+                name: "get_weather",
+                description: "Get the weather for a given location.",
+                AGUIDojoServerSerializerContext.Default.Options)]);
+    }
+
+    public static ChatClientAgent CreateHumanInTheLoop()
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        return chatClient.AsIChatClient().CreateAIAgent(
+            name: "HumanInTheLoopAgent",
+            description: "An agent that involves human feedback in its decision-making process using Azure OpenAI");
+    }
+
+    public static ChatClientAgent CreateToolBasedGenerativeUI()
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        return chatClient.AsIChatClient().CreateAIAgent(
+            name: "ToolBasedGenerativeUIAgent",
+            description: "An agent that uses tools to generate user interfaces using Azure OpenAI");
+    }
+
+    public static ChatClientAgent CreateAgenticUI()
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        return chatClient.AsIChatClient().CreateAIAgent(
+            name: "AgenticUIAgent",
+            description: "An agent that generates agentic user interfaces using Azure OpenAI");
+    }
+
+    public static AIAgent CreateSharedState(JsonSerializerOptions options)
+    {
+        ChatClient chatClient = s_azureOpenAIClient!.GetChatClient(s_deploymentName!);
+
+        var baseAgent = chatClient.AsIChatClient().CreateAIAgent(
+            name: "SharedStateAgent",
+            description: "An agent that demonstrates shared state patterns using Azure OpenAI");
+
+        return new SharedStateAgent(baseAgent, options);
+    }
+
+    [Description("Get the weather for a given location.")]
+    private static WeatherInfo GetWeather([Description("The location to get the weather for.")] string location) => new()
+    {
+        Temperature = 20,
+        Conditions = "sunny",
+        Humidity = 50,
+        WindSpeed = 10,
+        FeelsLike = 25
+    };
+}

dotnet/samples/AGUIClientServer/AGUIDojoServer/Ingredient.cs

@@ -0,0 +1,17 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer;
+
+internal sealed class Ingredient
+{
+    [JsonPropertyName("icon")]
+    public string Icon { get; set; } = string.Empty;
+
+    [JsonPropertyName("name")]
+    public string Name { get; set; } = string.Empty;
+
+    [JsonPropertyName("amount")]
+    public string Amount { get; set; } = string.Empty;
+}

dotnet/samples/AGUIClientServer/AGUIDojoServer/Program.cs

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using AGUIDojoServer;
+using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
+using Microsoft.AspNetCore.HttpLogging;
+using Microsoft.Extensions.Options;
+
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddHttpLogging(logging =>
+{
+    logging.LoggingFields = HttpLoggingFields.RequestPropertiesAndHeaders | HttpLoggingFields.RequestBody
+        | HttpLoggingFields.ResponsePropertiesAndHeaders | HttpLoggingFields.ResponseBody;
+    logging.RequestBodyLogLimit = int.MaxValue;
+    logging.ResponseBodyLogLimit = int.MaxValue;
+});
+
+builder.Services.AddHttpClient().AddLogging();
+builder.Services.ConfigureHttpJsonOptions(options => options.SerializerOptions.TypeInfoResolverChain.Add(AGUIDojoServerSerializerContext.Default));
+builder.Services.AddAGUI();
+
+WebApplication app = builder.Build();
+
+app.UseHttpLogging();
+
+// Initialize the factory
+ChatClientAgentFactory.Initialize(app.Configuration);
+
+// Map the AG-UI agent endpoints for different scenarios
+app.MapAGUI("/agentic_chat", ChatClientAgentFactory.CreateAgenticChat());
+
+app.MapAGUI("/backend_tool_rendering", ChatClientAgentFactory.CreateBackendToolRendering());
+
+app.MapAGUI("/human_in_the_loop", ChatClientAgentFactory.CreateHumanInTheLoop());
+
+app.MapAGUI("/tool_based_generative_ui", ChatClientAgentFactory.CreateToolBasedGenerativeUI());
+
+app.MapAGUI("/agentic_generative_ui", ChatClientAgentFactory.CreateAgenticUI());
+
+var jsonOptions = app.Services.GetRequiredService<IOptions<Microsoft.AspNetCore.Http.Json.JsonOptions>>();
+app.MapAGUI("/shared_state", ChatClientAgentFactory.CreateSharedState(jsonOptions.Value.SerializerOptions));
+
+await app.RunAsync();
+
+public partial class Program { }

dotnet/samples/AGUIClientServer/AGUIDojoServer/Properties/launchSettings.json

@@ -0,0 +1,12 @@
+{
+  "profiles": {
+    "AGUIDojoServer": {
+      "commandName": "Project",
+      "launchBrowser": true,
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      },
+      "applicationUrl": "http://localhost:5018"
+    }
+  }
+}

dotnet/samples/AGUIClientServer/AGUIDojoServer/Recipe.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer;
+
+internal sealed class Recipe
+{
+    [JsonPropertyName("title")]
+    public string Title { get; set; } = string.Empty;
+
+    [JsonPropertyName("skill_level")]
+    public string SkillLevel { get; set; } = string.Empty;
+
+    [JsonPropertyName("cooking_time")]
+    public string CookingTime { get; set; } = string.Empty;
+
+    [JsonPropertyName("special_preferences")]
+    public List<string> SpecialPreferences { get; set; } = [];
+
+    [JsonPropertyName("ingredients")]
+    public List<Ingredient> Ingredients { get; set; } = [];
+
+    [JsonPropertyName("instructions")]
+    public List<string> Instructions { get; set; } = [];
+}

dotnet/samples/AGUIClientServer/AGUIDojoServer/RecipeResponse.cs

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer;
+
+#pragma warning disable CA1812 // Used for the JsonSchema response format
+internal sealed class RecipeResponse
+#pragma warning restore CA1812
+{
+    [JsonPropertyName("recipe")]
+    public Recipe Recipe { get; set; } = new();
+}

dotnet/samples/AGUIClientServer/AGUIDojoServer/SharedStateAgent.cs

@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace AGUIDojoServer;
+
+[SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated by ChatClientAgentFactory.CreateSharedState")]
+internal sealed class SharedStateAgent : DelegatingAIAgent
+{
+    private readonly JsonSerializerOptions _jsonSerializerOptions;
+
+    public SharedStateAgent(AIAgent innerAgent, JsonSerializerOptions jsonSerializerOptions)
+        : base(innerAgent)
+    {
+        this._jsonSerializerOptions = jsonSerializerOptions;
+    }
+
+    public override Task<AgentRunResponse> RunAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        return this.RunStreamingAsync(messages, thread, options, cancellationToken).ToAgentRunResponseAsync(cancellationToken);
+    }
+
+    public override async IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        if (options is not ChatClientAgentRunOptions { ChatOptions.AdditionalProperties: { } properties } chatRunOptions ||
+            !properties.TryGetValue("ag_ui_state", out JsonElement state))
+        {
+            await foreach (var update in this.InnerAgent.RunStreamingAsync(messages, thread, options, cancellationToken).ConfigureAwait(false))
+            {
+                yield return update;
+            }
+            yield break;
+        }
+
+        var firstRunOptions = new ChatClientAgentRunOptions
+        {
+            ChatOptions = chatRunOptions.ChatOptions.Clone(),
+            AllowBackgroundResponses = chatRunOptions.AllowBackgroundResponses,
+            ContinuationToken = chatRunOptions.ContinuationToken,
+            ChatClientFactory = chatRunOptions.ChatClientFactory,
+        };
+
+        // Configure JSON schema response format for structured state output
+        firstRunOptions.ChatOptions.ResponseFormat = ChatResponseFormat.ForJsonSchema<RecipeResponse>(
+            schemaName: "RecipeResponse",
+            schemaDescription: "A response containing a recipe with title, skill level, cooking time, preferences, ingredients, and instructions");
+
+        ChatMessage stateUpdateMessage = new(
+            ChatRole.System,
+            [
+                new TextContent("Here is the current state in JSON format:"),
+                    new TextContent(state.GetRawText()),
+                    new TextContent("The new state is:")
+            ]);
+
+        var firstRunMessages = messages.Append(stateUpdateMessage);
+
+        var allUpdates = new List<AgentRunResponseUpdate>();
+        await foreach (var update in this.InnerAgent.RunStreamingAsync(firstRunMessages, thread, firstRunOptions, cancellationToken).ConfigureAwait(false))
+        {
+            allUpdates.Add(update);
+
+            // Yield all non-text updates (tool calls, etc.)
+            bool hasNonTextContent = update.Contents.Any(c => c is not TextContent);
+            if (hasNonTextContent)
+            {
+                yield return update;
+            }
+        }
+
+        var response = allUpdates.ToAgentRunResponse();
+
+        if (response.TryDeserialize(this._jsonSerializerOptions, out JsonElement stateSnapshot))
+        {
+            byte[] stateBytes = JsonSerializer.SerializeToUtf8Bytes(
+                stateSnapshot,
+                this._jsonSerializerOptions.GetTypeInfo(typeof(JsonElement)));
+            yield return new AgentRunResponseUpdate
+            {
+                Contents = [new DataContent(stateBytes, "application/json")]
+            };
+        }
+        else
+        {
+            yield break;
+        }
+
+        var secondRunMessages = messages.Concat(response.Messages).Append(
+            new ChatMessage(
+                ChatRole.System,
+                [new TextContent("Please provide a concise summary of the state changes in at most two sentences.")]));
+
+        await foreach (var update in this.InnerAgent.RunStreamingAsync(secondRunMessages, thread, options, cancellationToken).ConfigureAwait(false))
+        {
+            yield return update;
+        }
+    }
+}

dotnet/samples/AGUIClientServer/AGUIDojoServer/WeatherInfo.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace AGUIDojoServer;
+
+internal sealed class WeatherInfo
+{
+    [JsonPropertyName("temperature")]
+    public int Temperature { get; init; }
+
+    [JsonPropertyName("conditions")]
+    public string Conditions { get; init; } = string.Empty;
+
+    [JsonPropertyName("humidity")]
+    public int Humidity { get; init; }
+
+    [JsonPropertyName("wind_speed")]
+    public int WindSpeed { get; init; }
+
+    [JsonPropertyName("feelsLike")]
+    public int FeelsLike { get; init; }
+}