Update package versions (#3838)

* Replace Hosted*Tool classes with client static factory methods

* fixed failing test

* mypy fix

* mypy fix 2

* declarative mypy fix

* addressed comments

* ToolProtocol removal

* fixed test

* agents mypy fix

* fix failing tests

* mypy fix

* addressed comments

* fixed tests

* addressed comments + added factory method overrides for azureai v2 client

* mypy fix

* added kwargs to azureai tool methods

* fixed in test

* _sessions fix

* test fix

.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,38 @@
+{
+  "name": "C# (.NET)",
+  //"image": "mcr.microsoft.com/devcontainers/dotnet",
+  // Workaround for https://github.com/devcontainers/images/issues/1752
+  "build": {
+    "dockerfile": "dotnet.Dockerfile"
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/azure-cli:1.2.9": {},
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "version": "2"
+    },
+    "ghcr.io/devcontainers/features/powershell:1": {
+      "version": "latest"
+    },
+    "ghcr.io/azure/azure-dev/azd:0": {
+      "version": "latest"
+    },
+    "ghcr.io/devcontainers/features/dotnet:2": {
+      "version": "none",
+      "dotnetRuntimeVersions": "10.0",
+      "aspNetCoreRuntimeVersions": "10.0"
+    },
+    "ghcr.io/devcontainers/features/copilot-cli:1": {}
+  },
+  "workspaceFolder": "/workspaces/agent-framework/dotnet/",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "GitHub.copilot",
+        "GitHub.vscode-github-actions",
+        "ms-dotnettools.csdevkit",
+        "vscode-icons-team.vscode-icons",
+        "ms-windows-ai-studio.windows-ai-studio"
+      ]
+    }
+  }
+}

.devcontainer/dotnet/dotnet.Dockerfile

@@ -0,0 +1,5 @@
+FROM mcr.microsoft.com/devcontainers/universal:latest
+
+# Remove Yarn repository with expired GPG key to prevent apt-get update failures
+# Tracking issue: https://github.com/devcontainers/images/issues/1752
+RUN rm -f /etc/apt/sources.list.d/yarn.list

.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,7 @@
+# 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
+python/packages/durabletask/ @microsoft/agentframework-durabletask-developers
+python/samples/getting_started/azure_functions/ @microsoft/agentframework-durabletask-developers
+python/samples/getting_started/durabletask/ @microsoft/agentframework-durabletask-developers

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Documentation
+    url: https://aka.ms/agent-framework
+    about: Check out the official documentation for guides and API reference.
+  - name: Discussions
+    url: https://github.com/microsoft/agent-framework/discussions
+    about: Ask questions about Agent Framework.

.github/ISSUE_TEMPLATE/dotnet-issue.yml

@@ -0,0 +1,70 @@
+name: .NET Bug Report
+description: Report a bug in the Agent Framework .NET SDK
+title: ".NET: [Bug]: "
+labels: ["bug", ".NET"]
+type: bug
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Please provide a clear and detailed description of the bug.
+      placeholder: |
+        - What happened?
+        - What did you expect to happen?
+        - Steps to reproduce the issue
+    validations:
+      required: true
+
+  - type: textarea
+    id: code-sample
+    attributes:
+      label: Code Sample
+      description: If applicable, provide a minimal code sample that demonstrates the issue.
+      placeholder: |
+        ```csharp
+        // Your code here
+        ```
+      render: markdown
+    validations:
+      required: false
+
+  - type: textarea
+    id: error-messages
+    attributes:
+      label: Error Messages / Stack Traces
+      description: Include any error messages or stack traces you received.
+      placeholder: |
+        ```
+        Paste error messages or stack traces here
+        ```
+      render: markdown
+    validations:
+      required: false
+
+  - type: input
+    id: dotnet-packages
+    attributes:
+      label: Package Versions
+      description: List the Microsoft.Agents.* packages and versions you are using
+      placeholder: "e.g., Microsoft.Agents.AI.Abstractions: 1.0.0, Microsoft.Agents.AI.OpenAI: 1.0.0"
+    validations:
+      required: true
+
+  - type: input
+    id: dotnet-version
+    attributes:
+      label: .NET Version
+      description: What version of .NET are you using?
+      placeholder: "e.g., .NET 8.0"
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context or screenshots that might be helpful.
+      placeholder: "Any additional information..."
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,51 @@
+name: Feature Request
+description: Request a new feature for Microsoft Agent Framework
+title: "[Feature]: "
+type: feature
+body:
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Please describe the feature you'd like and why it would be useful.
+      placeholder: |
+        Describe the feature you're requesting:
+        - What problem does it solve?
+        - What would the expected behavior be?
+        - Are there any alternatives you've considered?
+    validations:
+      required: true
+
+  - type: textarea
+    id: code-sample
+    attributes:
+      label: Code Sample
+      description: If applicable, provide a code sample showing how you'd like to use this feature.
+      placeholder: |
+        ```python
+        # Your code here
+        ```
+
+        or
+
+        ```csharp
+        // Your code here
+        ```
+      render: markdown
+    validations:
+      required: false
+
+  - type: dropdown
+    id: language
+    attributes:
+      label: Language/SDK
+      description: Which language/SDK does this feature apply to?
+      options:
+        - Both
+        - .NET
+        - Python
+        - Other / Not Applicable
+      default: 0
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/python-issue.yml

@@ -0,0 +1,70 @@
+name: Python Bug Report
+description: Report a bug in the Agent Framework Python SDK
+title: "Python: [Bug]: "
+labels: ["bug", "Python"]
+type: bug
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: Please provide a clear and detailed description of the bug.
+      placeholder: |
+        - What happened?
+        - What did you expect to happen?
+        - Steps to reproduce the issue
+    validations:
+      required: true
+
+  - type: textarea
+    id: code-sample
+    attributes:
+      label: Code Sample
+      description: If applicable, provide a minimal code sample that demonstrates the issue.
+      placeholder: |
+        ```python
+        # Your code here
+        ```
+      render: markdown
+    validations:
+      required: false
+
+  - type: textarea
+    id: error-messages
+    attributes:
+      label: Error Messages / Stack Traces
+      description: Include any error messages or stack traces you received.
+      placeholder: |
+        ```
+        Paste error messages or stack traces here
+        ```
+      render: markdown
+    validations:
+      required: false
+
+  - type: input
+    id: python-packages
+    attributes:
+      label: Package Versions
+      description: List the agent-framework-* packages and versions you are using
+      placeholder: "e.g., agent-framework-core: 1.0.0, agent-framework-azure-ai: 1.0.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: What version of Python are you using?
+      placeholder: "e.g., Python 3.11"
+    validations:
+      required: false
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Add any other context or screenshots that might be helpful.
+      placeholder: "Any additional information..."
+    validations:
+      required: false

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

@@ -0,0 +1,48 @@
+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 -e DTS_USE_DYNAMIC_TASK_HUBS=true 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: Start Redis
+        shell: bash
+        run: |
+          if [ "$(docker ps -aq -f name=redis)" ]; then
+            echo "Stopping and removing existing Redis"
+            docker rm -f redis
+          fi
+          echo "Starting Redis"
+          docker run -d --name redis -p 6379:6379 redis:latest
+          echo "Waiting for Redis to be ready"
+          timeout 30 bash -c 'until docker exec redis redis-cli ping | grep -q PONG; do sleep 1; done'
+          echo "Redis 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,19 @@
+# GitHub Copilot Instructions
+
+Microsoft Agent Framework - a multi-language framework for building, orchestrating, and deploying AI agents.
+
+## Repository Structure
+
+- `python/` - Python implementation → see [python/AGENTS.md](../python/AGENTS.md)
+- `dotnet/` - C#/.NET implementation → see [dotnet/AGENTS.md](../dotnet/AGENTS.md)
+- `docs/` - Design documents and architectural decision records
+
+## Architectural Decision Records (ADRs)
+
+ADRs in `docs/decisions/` capture significant design decisions and their rationale. They document considered alternatives, trade-offs, and the reasoning behind choices.
+
+**Templates:**
+- `adr-template.md` - Full template with detailed sections
+- `adr-short-template.md` - Abbreviated template for simpler decisions
+
+When proposing architectural changes, create an ADR to capture options considered and the decision rationale. See [docs/decisions/README.md](../docs/decisions/README.md) for the full process.

.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/instructions/durabletask-dotnet.instructions.md

@@ -0,0 +1,17 @@
+---
+applyTo: "dotnet/src/Microsoft.Agents.AI.DurableTask/**,dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/**"
+---
+
+# Durable Task area code instructions
+
+The following guidelines apply to pull requests that modify files under
+`dotnet/src/Microsoft.Agents.AI.DurableTask/**` or
+`dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/**`:
+
+## CHANGELOG.md
+
+- Each pull request that modifies code should add just one bulleted entry to the `CHANGELOG.md` file containing a change title (usually the PR title) and a link to the PR itself.
+- New PRs should be added to the top of the `CHANGELOG.md` file under a "## [Unreleased]" heading.
+- If the PR is the first since the last release, the existing "## [Unreleased]" heading should be replaced with a "## v[X.Y.Z]" heading and the PRs since the last release should be added to the new "## [Unreleased]" heading.
+- The style of new `CHANGELOG.md` entries should match the style of the other entries in the file.
+- If the PR introduces a breaking change, the changelog entry should be prefixed with "[BREAKING]".

.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@v6
         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,21 +9,16 @@ 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
 
 env:
   COVERAGE_THRESHOLD: 80
+  COVERAGE_FRAMEWORK: net10.0 # framework target for which we run/report code coverage
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -34,28 +29,73 @@ permissions:
   id-token: "write"
 
 jobs:
+  paths-filter:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      dotnetChanges: ${{ steps.filter.outputs.dotnet }}
+      cosmosDbChanges: ${{ steps.filter.outputs.cosmosdb }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            dotnet:
+              - 'dotnet/**'
+            cosmosdb:
+              - 'dotnet/src/Microsoft.Agents.AI.CosmosNoSql/**'
+      # run only if 'dotnet' files were changed
+      - name: dotnet tests
+        if: steps.filter.outputs.dotnet == 'true'
+        run: echo "Dotnet file"
+      - name: dotnet CosmosDB tests
+        if: steps.filter.outputs.cosmosdb == 'true'
+        run: echo "Dotnet CosmosDB changes"
+      # 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:
         include:
-          - { targetFramework: "net9.0", os: "ubuntu-latest", configuration: Release, integration-tests: true, environment: "integration" }
-          - { targetFramework: "net9.0", os: "ubuntu-latest", configuration: Debug }
-          - { targetFramework: "net9.0", os: "windows-latest", configuration: Release }
+          - { targetFramework: "net10.0", os: "ubuntu-latest", configuration: Release, integration-tests: true, environment: "integration" }
+          - { targetFramework: "net9.0", os: "windows-latest", configuration: Debug }
+          - { targetFramework: "net8.0", os: "ubuntu-latest", configuration: Release }
           - { targetFramework: "net472", os: "windows-latest", configuration: Release, integration-tests: true, environment: "integration" }
 
     runs-on: ${{ matrix.os }}
     environment: ${{ matrix.environment }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
-          persist-credentials: false
-          sparse-checkout: |
-            .
-            .github
-            dotnet
+            persist-credentials: false
+            sparse-checkout: |
+              .
+              .github
+              dotnet
+              python
+              workflow-samples
+
+      # Start Cosmos DB Emulator for all integration tests and only for unit tests when CosmosDB changes happened)
+      - name: Start Azure Cosmos DB Emulator
+        if: ${{ runner.os == 'Windows' && (needs.paths-filter.outputs.cosmosDbChanges == 'true' || (github.event_name != 'pull_request' && matrix.integration-tests)) }}
+        shell: pwsh
+        run: |
+          Write-Host "Launching Azure Cosmos DB Emulator"
+          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
+          Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
+          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
+
       - name: Setup dotnet
-        uses: actions/setup-dotnet@v4.3.1
+        uses: actions/setup-dotnet@v5.1.0
         with:
           global-json-file: ${{ github.workspace }}/dotnet/global.json
       - name: Build dotnet solutions
@@ -92,7 +132,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
@@ -100,17 +140,33 @@ jobs:
           popd
           rm -rf "$TEMP_DIR"
 
-      - name: Run Unit Tests Windows
+      - name: Run Unit Tests
         shell: bash
         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
+              if [[ "${{ matrix.targetFramework }}" == "${{ env.COVERAGE_FRAMEWORK }}" ]]; 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
+                dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx
+              fi
+            else
+              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
+            fi
           done
-      
+        env:
+          # Cosmos DB Emulator connection settings
+          COSMOSDB_ENDPOINT: https://localhost:8081
+          COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
+
       - name: Log event name and matrix integration-tests
-        shell: bash 
-        run: echo "github.event_name:${{ github.event_name }} matrix.integration-tests:${{ matrix.integration-tests }} github.event.action:${{ github.event.action }} github.event.pull_request.merged:${{ github.event.pull_request.merged }}" 
+        shell: bash
+        run: echo "github.event_name:${{ github.event_name }} matrix.integration-tests:${{ matrix.integration-tests }} github.event.action:${{ github.event.action }} github.event.pull_request.merged:${{ github.event.pull_request.merged }}"
 
       - name: Azure CLI Login
         if: github.event_name != 'pull_request' && matrix.integration-tests
@@ -120,38 +176,68 @@ 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 --filter "Category!=IntegrationDisabled"
+            else
+              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
+            fi
           done
         env:
+          # Cosmos DB Emulator connection settings
+          COSMOSDB_ENDPOINT: https://localhost:8081
+          COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
           # OpenAI Models
           OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
           OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
           OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}
+          # Azure OpenAI Models
+          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
           # Azure AI Foundry
           AzureAI__Endpoint: ${{ secrets.AZUREAI__ENDPOINT }}
           AzureAI__DeploymentName: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
+          AzureAI__BingConnectionId: ${{ vars.AZUREAI__BINGCONECTIONID }}
+          FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
+          FOUNDRY_MEDIA_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MEDIA_DEPLOYMENT_NAME }}
+          FOUNDRY_MODEL_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MODEL_DEPLOYMENT_NAME }}
+          FOUNDRY_CONNECTION_GROUNDING_TOOL: ${{ vars.FOUNDRY_CONNECTION_GROUNDING_TOOL }}
 
       # Generate test reports and check coverage
       - name: Generate test reports
-        uses: danielpalme/ReportGenerator-GitHub-Action@5.4.10
+        if: matrix.targetFramework == env.COVERAGE_FRAMEWORK
+        uses: danielpalme/ReportGenerator-GitHub-Action@5.5.1
         with:
           reports: "./TestResults/Coverage/**/coverage.cobertura.xml"
           targetdir: "./TestResults/Reports"
           reporttypes: "HtmlInline;JsonSummary"
 
       - name: Upload coverage report artifact
-        uses: actions/upload-artifact@v4
+        if: matrix.targetFramework == env.COVERAGE_FRAMEWORK
+        uses: actions/upload-artifact@v6
         with:
           name: CoverageReport-${{ matrix.os }}-${{ matrix.targetFramework }}-${{ matrix.configuration }} # Artifact name
           path: ./TestResults/Reports # Directory containing files to upload
 
       - name: Check coverage
+        if: matrix.targetFramework == env.COVERAGE_FRAMEWORK
         shell: pwsh
         run: .github/workflows/dotnet-check-coverage.ps1 -JsonReportPath "TestResults/Reports/Summary.json" -CoverageThreshold $env:COVERAGE_THRESHOLD
 
@@ -187,13 +273,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

@@ -22,7 +22,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - { dotnet: "9.0", configuration: Release, os: ubuntu-latest }
+          - { dotnet: "10.0", configuration: Release, os: ubuntu-latest }
 
     runs-on: ${{ matrix.os }}
     env:
@@ -30,7 +30,7 @@ jobs:
 
     steps:
       - name: Check out code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         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,27 +22,91 @@ jobs:
             let title = context.payload.issue.title
 
             // Define the labels array
-            let labels = ["triage"]
+            let labels = []
 
-            // 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))) {
-              // Add the 'python' label to the array
-              labels.push("python")
+            // 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
             }
 
-            // Check if the body or the title contains the words 'dotnet', '.net', 'c#' or 'csharp' (case-insensitive)
-            if ((body != null && body.match(/.net/i)) || (title != null && title.match(/.net/i)) ||
-                (body != null && body.match(/dotnet/i)) || (title != null && title.match(/dotnet/i)) ||
-                (body != null && body.match(/C#/i)) || (title != null && title.match(/C#/i)) ||
-                (body != null && body.match(/csharp/i)) || (title != null && title.match(/csharp/i))) {
-              // Add the '.NET' label to the array
-              labels.push(".NET")
+            // Only add triage label if the author is not in the team
+            if (!isTeamMember) {
+              labels.push("triage")
             }
 
-            // 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
-            });
+            // Helper function to extract field value from issue form body
+            // Issue forms format fields as: ### Field Name\n\nValue
+            function getFormFieldValue(body, fieldName) {
+              if (!body) return null
+              const regex = new RegExp(`###\\s*${fieldName}\\s*\\n\\n([^\\n#]+)`, 'i')
+              const match = body.match(regex)
+              return match ? match[1].trim() : null
+            }
+
+            // Check for language from issue form dropdown first
+            const languageField = getFormFieldValue(body, 'Language')
+            let languageLabelAdded = false
+
+            if (languageField) {
+              if (languageField === 'Python') {
+                labels.push("python")
+                languageLabelAdded = true
+              } else if (languageField === '.NET') {
+                labels.push(".NET")
+                languageLabelAdded = true
+              }
+              // 'None / Not Applicable' - don't add any language label
+            }
+
+            // Fallback: Check if the body or the title contains the word 'python' (case-insensitive)
+            // Only if language wasn't already determined from the form field
+            if (!languageLabelAdded) {
+              if ((body != null && body.match(/python/i)) || (title != null && title.match(/python/i))) {
+                // Add the 'python' label to the array
+                labels.push("python")
+              }
+
+              // Check if the body or the title contains the words 'dotnet', '.net', 'c#' or 'csharp' (case-insensitive)
+              if ((body != null && body.match(/\.net/i)) || (title != null && title.match(/\.net/i)) ||
+                  (body != null && body.match(/dotnet/i)) || (title != null && title.match(/dotnet/i)) ||
+                  (body != null && body.match(/C#/i)) || (title != null && title.match(/C#/i)) ||
+                  (body != null && body.match(/csharp/i)) || (title != null && title.match(/csharp/i))) {
+                // Add the '.NET' label to the array
+                labels.push(".NET")
+              }
+            }
+
+            // Check for issue type from issue form dropdown
+            const issueTypeField = getFormFieldValue(body, 'Type of Issue')
+            if (issueTypeField) {
+              if (issueTypeField === 'Bug') {
+                labels.push("bug")
+              } else if (issueTypeField === 'Feature Request') {
+                labels.push("enhancement")
+              } else if (issueTypeField === 'Question') {
+                labels.push("question")
+              }
+            }
+
+            // 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@v6
+        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/merge-gatekeeper.yml

@@ -29,3 +29,4 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           timeout: 3600
           interval: 30
+          ignored: CodeQL,CodeQL analysis (csharp)

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

@@ -0,0 +1,266 @@
+#!/usr/bin/env python3
+# Copyright (c) Microsoft. All rights reserved.
+"""Check Python test coverage against threshold for enforced modules.
+
+This script parses a Cobertura XML coverage report and enforces a minimum
+coverage threshold on specific modules. Non-enforced modules are reported
+for visibility but don't block the build.
+
+Usage:
+    python python-check-coverage.py <coverage-xml-path> <threshold>
+
+Example:
+    python python-check-coverage.py python-coverage.xml 85
+"""
+
+import sys
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+
+# =============================================================================
+# ENFORCED MODULES CONFIGURATION
+# =============================================================================
+# Add or remove modules from this set to control which packages must meet
+# the coverage threshold. Only these modules will fail the build if below
+# threshold. Other modules are reported for visibility only.
+#
+# Module paths should match the package paths as they appear in the coverage
+# report (e.g., "packages.azure-ai.agent_framework_azure_ai" for packages/azure-ai).
+# Sub-modules can be included by specifying their full path.
+# =============================================================================
+ENFORCED_MODULES: set[str] = {
+    "packages.azure-ai.agent_framework_azure_ai",
+    # Add more modules here as coverage improves:
+    # "packages.core.agent_framework",
+    # "packages.core.agent_framework._workflows",
+    # "packages.anthropic.agent_framework_anthropic",
+}
+
+
+@dataclass
+class PackageCoverage:
+    """Coverage data for a single package."""
+
+    name: str
+    line_rate: float
+    branch_rate: float
+    lines_valid: int
+    lines_covered: int
+    branches_valid: int
+    branches_covered: int
+
+    @property
+    def line_coverage_percent(self) -> float:
+        """Return line coverage as a percentage."""
+        return self.line_rate * 100
+
+    @property
+    def branch_coverage_percent(self) -> float:
+        """Return branch coverage as a percentage."""
+        return self.branch_rate * 100
+
+
+def parse_coverage_xml(xml_path: str) -> tuple[dict[str, PackageCoverage], float, float]:
+    """Parse Cobertura XML and extract per-package coverage data.
+
+    Args:
+        xml_path: Path to the Cobertura XML coverage report.
+
+    Returns:
+        A tuple of (packages_dict, overall_line_rate, overall_branch_rate).
+    """
+    tree = ET.parse(xml_path)
+    root = tree.getroot()
+
+    # Get overall coverage from root element
+    overall_line_rate = float(root.get("line-rate", 0))
+    overall_branch_rate = float(root.get("branch-rate", 0))
+
+    packages: dict[str, PackageCoverage] = {}
+
+    for package in root.findall(".//package"):
+        package_path = package.get("name", "unknown")
+
+        line_rate = float(package.get("line-rate", 0))
+        branch_rate = float(package.get("branch-rate", 0))
+
+        # Count lines and branches from classes within this package
+        lines_valid = 0
+        lines_covered = 0
+        branches_valid = 0
+        branches_covered = 0
+
+        for class_elem in package.findall(".//class"):
+            for line in class_elem.findall(".//line"):
+                lines_valid += 1
+                if int(line.get("hits", 0)) > 0:
+                    lines_covered += 1
+                # Branch coverage from line elements
+                if line.get("branch") == "true":
+                    condition_coverage = line.get("condition-coverage", "")
+                    if condition_coverage:
+                        # Parse "X% (covered/total)" format
+                        try:
+                            coverage_parts = condition_coverage.split("(")[1].rstrip(")").split("/")
+                            branches_covered += int(coverage_parts[0])
+                            branches_valid += int(coverage_parts[1])
+                        except (IndexError, ValueError):
+                            # Ignore malformed condition-coverage strings; treat this line as having no branch data.
+                            pass
+
+        # Use full package path as the key (no aggregation)
+        packages[package_path] = PackageCoverage(
+            name=package_path,
+            line_rate=line_rate if lines_valid == 0 else lines_covered / lines_valid,
+            branch_rate=branch_rate if branches_valid == 0 else branches_covered / branches_valid,
+            lines_valid=lines_valid,
+            lines_covered=lines_covered,
+            branches_valid=branches_valid,
+            branches_covered=branches_covered,
+        )
+
+    return packages, overall_line_rate, overall_branch_rate
+
+
+def format_coverage_value(coverage: float, threshold: float, is_enforced: bool) -> str:
+    """Format a coverage value with optional pass/fail indicator.
+
+    Args:
+        coverage: Coverage percentage (0-100).
+        threshold: Minimum required coverage percentage.
+        is_enforced: Whether this module is enforced.
+
+    Returns:
+        Formatted string like "85.5%" or "85.5% ✅" or "75.0% ❌".
+    """
+    formatted = f"{coverage:.1f}%"
+    if is_enforced:
+        icon = "✅" if coverage >= threshold else "❌"
+        formatted = f"{formatted} {icon}"
+    return formatted
+
+
+def print_coverage_table(
+    packages: dict[str, PackageCoverage],
+    threshold: float,
+    overall_line_rate: float,
+    overall_branch_rate: float,
+) -> None:
+    """Print a formatted coverage summary table.
+
+    Args:
+        packages: Dictionary of package name to coverage data.
+        threshold: Minimum required coverage percentage.
+        overall_line_rate: Overall line coverage rate (0-1).
+        overall_branch_rate: Overall branch coverage rate (0-1).
+    """
+    print("\n" + "=" * 80)
+    print("PYTHON TEST COVERAGE REPORT")
+    print("=" * 80)
+
+    # Overall coverage
+    print(f"\nOverall Line Coverage:   {overall_line_rate * 100:.1f}%")
+    print(f"Overall Branch Coverage: {overall_branch_rate * 100:.1f}%")
+    print(f"Threshold:               {threshold}%")
+
+    # Package table
+    print("\n" + "-" * 110)
+    print(f"{'Package':<80} {'Lines':<15} {'Line Cov':<15}")
+    print("-" * 110)
+
+    # Sort: enforced modules first, then alphabetically
+    sorted_packages = sorted(
+        packages.values(),
+        key=lambda p: (p.name not in ENFORCED_MODULES, p.name),
+    )
+
+    for pkg in sorted_packages:
+        is_enforced = pkg.name in ENFORCED_MODULES
+        enforced_marker = "[ENFORCED] " if is_enforced else ""
+        line_cov = format_coverage_value(pkg.line_coverage_percent, threshold, is_enforced)
+        lines_info = f"{pkg.lines_covered}/{pkg.lines_valid}"
+        package_label = f"{enforced_marker}{pkg.name}"
+
+        print(f"{package_label:<80} {lines_info:<15} {line_cov:<15}")
+
+    print("-" * 110)
+
+
+def check_coverage(xml_path: str, threshold: float) -> bool:
+    """Check if all enforced modules meet the coverage threshold.
+
+    Args:
+        xml_path: Path to the Cobertura XML coverage report.
+        threshold: Minimum required coverage percentage.
+
+    Returns:
+        True if all enforced modules pass, False otherwise.
+    """
+    packages, overall_line_rate, overall_branch_rate = parse_coverage_xml(xml_path)
+
+    print_coverage_table(packages, threshold, overall_line_rate, overall_branch_rate)
+
+    # Check enforced modules
+    failed_modules: list[str] = []
+    missing_modules: list[str] = []
+
+    for module_name in ENFORCED_MODULES:
+        if module_name not in packages:
+            missing_modules.append(module_name)
+            continue
+
+        pkg = packages[module_name]
+        if pkg.line_coverage_percent < threshold:
+            failed_modules.append(f"{module_name} ({pkg.line_coverage_percent:.1f}%)")
+
+    # Report results
+    if missing_modules:
+        print(f"\n❌ FAILED: Enforced modules not found in coverage report: {', '.join(missing_modules)}")
+        return False
+
+    if failed_modules:
+        print(f"\n❌ FAILED: The following enforced modules are below {threshold}% coverage threshold:")
+        for module in failed_modules:
+            print(f"   - {module}")
+        print("\nTo fix: Add more tests to improve coverage for the failing modules.")
+        return False
+
+    if ENFORCED_MODULES:
+        found_enforced = [m for m in ENFORCED_MODULES if m in packages]
+        if found_enforced:
+            print(f"\n✅ PASSED: All enforced modules meet the {threshold}% coverage threshold.")
+
+    return True
+
+
+def main() -> int:
+    """Main entry point.
+
+    Returns:
+        Exit code: 0 for success, 1 for failure.
+    """
+    if len(sys.argv) != 3:
+        print(f"Usage: {sys.argv[0]} <coverage-xml-path> <threshold>")
+        print(f"Example: {sys.argv[0]} python-coverage.xml 85")
+        return 1
+
+    xml_path = sys.argv[1]
+    try:
+        threshold = float(sys.argv[2])
+    except ValueError:
+        print(f"Error: Invalid threshold value: {sys.argv[2]}")
+        return 1
+
+    try:
+        success = check_coverage(xml_path, threshold)
+        return 0 if success else 1
+    except FileNotFoundError:
+        print(f"Error: Coverage file not found: {xml_path}")
+        return 1
+    except ET.ParseError as e:
+        print(f"Error: Failed to parse coverage XML: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -8,11 +8,12 @@ on:
       - "python/**"
 
 env:
-  UV_SEMVER: "0.8.x"
+  # Configure a constant location for the uv cache
+  UV_CACHE_DIR: /tmp/.uv-cache
 
 jobs:
-  pre-commit:
-    name: Checks
+  pre-commit-hooks:
+    name: Pre-commit Hooks
     if: "!cancelled()"
     strategy:
       fail-fast: false
@@ -24,27 +25,119 @@ jobs:
       run:
         working-directory: ./python
     env:
-      # Configure a constant location for the uv cache
-      UV_CACHE_DIR: /tmp/.uv-cache
       UV_PYTHON: ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v6
         with:
-          version: ${{ env.UV_SEMVER }}
-          enable-cache: true
-          cache-suffix: ${{ runner.os }}-${{ matrix.python-version }}
-          cache-dependency-glob: "**/uv.lock"
-      - name: Install the project
-        run: uv sync --all-extras --dev
-      - uses: actions/cache@v3
+          fetch-depth: 0
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
         with:
-          path: ~/.cache/pre-commit
-          key: pre-commit|${{ matrix.python-version }}|${{ hashFiles('python/.pre-commit-config.yaml') }}
-      - uses: pre-commit/action@v3.0.1
-        name: Run Pre-Commit Hooks
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          UV_CACHE_DIR: /tmp/.uv-cache
+      - uses: actions/cache@v5
         with:
-          extra_args: --config python/.pre-commit-config.yaml --all-files
+          path: ~/.cache/prek
+          key: prek|${{ matrix.python-version }}|${{ hashFiles('python/.pre-commit-config.yaml') }}
+      - uses: j178/prek-action@v1
+        name: Run Pre-commit Hooks (excluding poe-check)
+        env:
+          SKIP: poe-check
+        with:
+          extra-args: --cd python --all-files
+
+  package-checks:
+    name: Package Checks
+    if: "!cancelled()"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    defaults:
+      run:
+        working-directory: ./python
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          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:
+          UV_CACHE_DIR: /tmp/.uv-cache
+      - name: Run fmt, lint, pyright in parallel across packages
+        run: uv run poe check-packages
+
+  samples-markdown:
+    name: Samples & Markdown
+    if: "!cancelled()"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    defaults:
+      run:
+        working-directory: ./python
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          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:
+          UV_CACHE_DIR: /tmp/.uv-cache
+      - name: Run samples lint
+        run: uv run poe samples-lint
+      - name: Run samples syntax check
+        run: uv run poe samples-syntax
+      - name: Run markdown code lint
+        run: uv run poe markdown-code-lint
+
+  mypy:
+    name: Mypy Checks
+    if: "!cancelled()"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10"]
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    defaults:
+      run:
+        working-directory: ./python
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          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:
+          UV_CACHE_DIR: /tmp/.uv-cache
       - 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@v6
+      - 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@v6
+      - 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@v6
+
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          # Configure a constant location for the uv cache
+          UV_CACHE_DIR: /tmp/.uv-cache
+
+      # Lab specific tests
+      - name: Run lab tests
+        run: cd packages/lab && uv run poe test
+
+      - name: Run lab lint
+        run: cd packages/lab && uv run poe lint
+
+      - name: Run lab format check
+        run: cd packages/lab && uv run poe fmt --check
+
+      - name: Run lab type checking
+        run: cd packages/lab && uv run poe pyright
+
+      - name: Run lab mypy
+        run: cd packages/lab && uv run poe mypy
+
+      # Surface failing tests
+      - name: Surface failing tests
+        if: always()
+        uses: pmeier/pytest-results-action@v0.7.2
+        with:
+          path: ./python/packages/lab/**.xml
+          summary: true
+          display-options: fEX
+          fail-on-empty: false
+          title: Lab Test Results

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

@@ -17,7 +17,7 @@ env:
   # Configure a constant location for the uv cache
   UV_CACHE_DIR: /tmp/.uv-cache
   RUN_INTEGRATION_TESTS: "true"
-  UV_SEMVER: "0.8.x"
+  RUN_SAMPLES_TESTS: ${{ vars.RUN_SAMPLES_TESTS }}
 
 jobs:
   paths-filter:
@@ -28,7 +28,7 @@ jobs:
     outputs:
       pythonChanges: ${{ steps.filter.outputs.python}}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: dorny/paths-filter@v3
         id: filter
         with:
@@ -43,8 +43,8 @@ jobs:
       - name: not python tests
         if: steps.filter.outputs.python != 'true'
         run: echo "NOT python file"
-  python-tests-main:
-    name: Python Tests - Main
+  python-tests-core:
+    name: Python Tests - Core
     needs: paths-filter
     if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
     runs-on: ${{ matrix.os }}
@@ -58,77 +58,33 @@ jobs:
     env:
       UV_PYTHON: ${{ matrix.python-version }}
       OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
+      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
       OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      PACKAGE_NAME: "main"
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v4
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v6
-        with:
-          version: ${{ env.UV_SEMVER }}
-          enable-cache: true
-          cache-suffix: ${{ runner.os }}-${{ matrix.python-version }}
-          cache-dependency-glob: "**/uv.lock"
-      - name: Install the project
-        run: |
-          uv sync --all-packages --all-extras --dev -U --prerelease=if-necessary-or-explicit
-      - name: Test with pytest
-        run: uv run poe --directory ./packages/${{ env.PACKAGE_NAME }} test --junitxml=coverage.xml
-        working-directory: ./python
-      - name: Move coverage file
-        run: |
-          mv ./packages/${{ env.PACKAGE_NAME }}/coverage.xml coverage_${{ env.PACKAGE_NAME }}.xml
-        working-directory: ./python
-      - name: Upload coverage artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-${{ env.PACKAGE_NAME }}
-          path: ./python/coverage_${{ env.PACKAGE_NAME }}.xml
-      - name: Surface failing tests
-        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
-        with:
-          path: ./python/**.xml
-          summary: true
-          display-options: fEX
-          fail-on-empty: true
-          title: Test results
-
-  python-tests-azure:
-    name: Python Tests - Azure
-    needs: paths-filter
-    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
-    runs-on: ${{ matrix.os }}
-    environment: ${{ matrix.environment }}
-    strategy:
-      fail-fast: true
-      matrix:
-        python-version: ["3.10"]
-        os: [ubuntu-latest]
-        environment: ["integration"]
-    env:
-      UV_PYTHON: ${{ matrix.python-version }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
       AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ secrets.AZUREOPENAI__ENDPOINT }}
-      PACKAGE_NAME: "azure"
+      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
+      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
+      # For Azure Functions integration tests
+      FUNCTIONS_WORKER_RUNTIME: "python"
+      DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
+      AzureWebJobsStorage: "UseDevelopmentStorage=true"
+
     defaults:
       run:
         working-directory: python
     steps:
-      - uses: actions/checkout@v4
-      - name: Set up uv
-        uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
         with:
-          version: ${{ env.UV_SEMVER }}
-          enable-cache: true
-          cache-suffix: ${{ runner.os }}-${{ matrix.python-version }}
-          cache-dependency-glob: "**/uv.lock"
-      - name: Install the project
-        run: |
-          uv sync --all-packages --all-extras --dev -U --prerelease=if-necessary-or-explicit
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          # Configure a constant location for the uv cache
+          UV_CACHE_DIR: /tmp/.uv-cache
       - name: Azure CLI Login
         if: github.event_name != 'pull_request'
         uses: azure/login@v2
@@ -136,18 +92,17 @@ 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
+        run: uv run poe all-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
         working-directory: ./python
-      - name: 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 +110,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 +127,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@v6
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
         with:
-          version: ${{ env.UV_SEMVER }}
-          enable-cache: true
-          cache-suffix: ${{ runner.os }}-${{ matrix.python-version }}
-          cache-dependency-glob: "**/uv.lock"
-      - name: Install the project
-        run: |
-          uv sync --all-packages --all-extras --dev -U --prerelease=if-necessary-or-explicit
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          # Configure a constant location for the uv cache
+          UV_CACHE_DIR: /tmp/.uv-cache
       - name: Azure CLI Login
         if: github.event_name != 'pull_request'
         uses: azure/login@v2
@@ -198,17 +152,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: 15
+        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist loadfile --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
         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 +167,31 @@ jobs:
           path: ./python/**.xml
           summary: true
           display-options: fEX
-          fail-on-empty: true
+          fail-on-empty: false
           title: Test results
+
+  # TODO: Add python-tests-lab
+
   python-integration-tests-check:
     if: always()
     runs-on: ubuntu-latest
     needs:
       [
-        python-tests-main,
-        python-tests-azure,
-        python-tests-foundry
+        python-tests-core,
+        python-tests-azure-ai
       ]
     steps:
 
       - name: Fail workflow if tests failed
         id: check_tests_failed
         if: contains(join(needs.*.result, ','), 'failure')
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: core.setFailed('Integration Tests Failed!')
 
       - name: Fail workflow if tests cancelled
         id: check_tests_cancelled
         if: contains(join(needs.*.result, ','), 'cancelled')
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: core.setFailed('Integration Tests Cancelled!')

.github/workflows/python-release.yml

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

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

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

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

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

.github/workflows/python-tests.yml

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

.gitignore

@@ -15,6 +15,7 @@ downloads/
 eggs/
 .eggs/
 lib/
+!python/packages/devui/frontend/src/lib/
 lib64/
 parts/
 sdist/
@@ -25,6 +26,7 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+TestResults/
 
 # PyInstaller
 #  Usually these files are written by a python script from a template
@@ -69,7 +71,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/build/
 
 # PyBuilder
 .pybuilder/
@@ -173,9 +175,55 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 
+**/.DS_Store
 .DS_Store
 
 # Visual Studio 2015/2017 cache/options directory
 .vs/
 
 **/.user/**
+
+# Temporary files
+*.~tmp
+*.~bak
+*.~swp
+*.~swo
+
+# Temporary directories
+*tmp/
+*temp/
+*.tmp/
+*.temp/
+tmp*/
+temp*/
+.tmp/
+.temp/
+
+# AI
+.claude/
+WARP.md
+**/memory-bank/
+**/projectBrief.md
+**/tmpclaude*
+
+# 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__/
+*/AzuriteConfig
+
+# Azure Functions local settings
+local.settings.json
+
+# Frontend
+**/frontend/node_modules/
+**/frontend/.vite/
+**/frontend/dist/
+
+# Database files
+*.db
+python/dotnet-ref

COMMUNITY.md

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

CONTRIBUTING.md

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

README.md

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

SUPPORT.md

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

TRANSPARENCY_FAQ.md

@@ -0,0 +1,141 @@
+# Responsible AI Transparency FAQs
+
+**What is Microsoft Agent Framework?**
+
+Microsoft Agent Framework is a comprehensive multi-language (C#/.NET and Python) framework for building, orchestrating, and deploying AI agents and multi-agent workflows. The system takes user instructions and conversation inputs and produces intelligent responses through AI agents that can integrate with various LLM providers (OpenAI, Azure OpenAI, Azure AI Foundry). It provides both simple chat agents and complex multi-agent workflows with graph-based orchestration.
+
+**What can Microsoft Agent Framework do?**
+
+The framework offers: 
+
+- **Agent Creation**: Build AI agents with custom instructions and tools
+- **Multi-Agent Orchestration**: Group chat, sequential, concurrent, and handoff patterns
+- **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, time-travel, and Human-in-the-loop
+- **Extensibility Framework**: Extend with native functions, A2A, Model Context Protocol (MCP)
+- **LLM Integration**: Support for OpenAI, Azure OpenAI, Azure AI Foundry, and other providers
+- **Runtime Support**: Both in-process and distributed agent execution
+
+**What is/are Microsoft Agent Framework's intended use(s)?**
+
+Intended uses include: 
+
+- **Enterprise AI Applications**: Building AI-powered business applications with multiple specialized agents
+- **Multi-Agent Collaboration**: Coordinating multiple AI agents for complex tasks (e.g., content creation with writer/reviewer agents)
+- **Workflow Automation**: Orchestrating AI agents and deterministic functions in business processes
+
+**How was Microsoft Agent Framework evaluated? What metrics are used to measure performance?**
+
+Microsoft Agent Framework is a development framework rather than a deployed AI system. The framework undergoes engineering testing for component functionality, integration testing for multi-agent scenarios, and conformance testing across .NET and Python implementations. However, AI performance metrics such as accuracy, helpfulness, and safety are dependent on the underlying LLM providers and specific application implementations. Developers using the framework should conduct application-specific evaluation including performance, safety, and accuracy testing appropriate to their chosen LLM providers, deployment contexts, and use cases.
+
+**What are the limitations of Microsoft Agent Framework? How can users minimize the impact of Microsoft Agent Framework's limitations when using the system?**
+
+Microsoft Agent Framework relies on existing LLMs. Using the framework retains common limitations of large language models, including:
+
+**LLM-Inherited Limitations**:
+
+- **Data Biases**: Large language models, trained on extensive data, can inadvertently carry biases present in the source data. Consequently, the models may generate outputs that could be potentially biased or unfair.
+- **Lack of Contextual Understanding**: Despite their impressive capabilities in language understanding and generation, these models exhibit limited real-world understanding, resulting in potential inaccuracies or nonsensical responses.
+- **Lack of Transparency**: Due to the complexity and size, large language models can act as 'black boxes,' making it difficult to comprehend the rationale behind specific outputs or decisions.
+- **Content Harms**: There are various types of content harms that large language models can cause. It is important to be aware of them when using these models, and to take actions to prevent them. It is recommended to leverage various content moderation services provided by different companies and institutions.
+- **Inaccurate or ungrounded content**: It is important to be aware and cautious not to entirely rely on a given language model for critical decisions or information that might have deep impact as it is not obvious how to prevent these models to fabricate content without high authority input sources.
+- **Potential for Misuse**: Without suitable safeguards, there is a risk that these models could be maliciously used for generating disinformation or harmful content.
+
+**Framework-Specific Limitations**:
+
+- **Platform Requirements**: Python 3.10+ required, specific .NET versions (.NET 8.0, 9.0, 10.0, netstandard2.0, net472)
+- **API Dependencies**: Requires proper configuration of LLM provider keys and endpoints
+- **Orchestration Features**: Advanced orchestration patterns including GroupChat, Sequential, and Concurrent workflows are now available in both Python and .NET implementations. See the respective language documentation for examples.
+- **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 

agent-samples/README.md

@@ -0,0 +1,3 @@
+# Declarative Agents
+
+This folder contains sample agent definitions that can be run using the declarative agent support, for python see the [declarative agent python sample folder](../python/samples/getting_started/declarative/).

agent-samples/azure/AzureOpenAI.yaml

@@ -0,0 +1,25 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions is the language specified by the user. You return your answers in a JSON format. You must include Chat as the type in your response.
+model:
+    id: =Env.AZURE_OPENAI_DEPLOYMENT_NAME
+    provider: AzureOpenAI
+    apiType: Chat
+    options:
+        temperature: 0.9
+        topP: 0.95
+outputSchema:
+    properties:
+        language:
+            kind: string
+            required: true
+            description: The language of the answer.
+        answer:
+            kind: string
+            required: true
+            description: The answer text.
+        type:
+            kind: string
+            required: true
+            description: The type of the response.

agent-samples/azure/AzureOpenAIAssistants.yaml

@@ -0,0 +1,25 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Assistants as the type in your response.
+model:
+    id: gpt-4o-mini
+    provider: AzureOpenAI
+    apiType: Assistants
+    options:
+        temperature: 0.9
+        topP: 0.95
+outputSchema:
+    properties:
+        language:
+            type: string
+            required: true
+            description: The language of the answer.
+        answer:
+            type: string
+            required: true
+            description: The answer text.
+        type:
+            type: string
+            required: true
+            description: The type of the response.

agent-samples/azure/AzureOpenAIChat.yaml

@@ -0,0 +1,25 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Chat as the type in your response.
+model:
+    id: gpt-4o-mini
+    provider: AzureOpenAI
+    apiType: Chat
+    options:
+        temperature: 0.9
+        topP: 0.95
+outputSchema:
+    properties:
+        language:
+            type: string
+            required: true
+            description: The language of the answer.
+        answer:
+            type: string
+            required: true
+            description: The answer text.
+        type:
+            type: string
+            required: true
+            description: The type of the response.

agent-samples/azure/AzureOpenAIResponses.yaml

@@ -0,0 +1,25 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Responses as the type in your response.
+model:
+    id: gpt-4o-mini
+    provider: AzureOpenAI
+    apiType: Responses
+    options:
+        temperature: 0.9
+        topP: 0.95
+outputSchema:
+    properties:
+        language:
+            type: string
+            required: true
+            description: The language of the answer.
+        answer:
+            type: string
+            required: true
+            description: The answer text.
+        type:
+            type: string
+            required: true
+            description: The type of the response.

agent-samples/chatclient/Assistant.yaml

@@ -0,0 +1,18 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format.
+model:
+    options:
+        temperature: 0.9
+        topP: 0.95
+outputSchema:
+    properties:
+        language:
+            type: string
+            required: true
+            description: The language of the answer.
+        answer:
+            type: string
+            required: true
+            description: The answer text.

agent-samples/chatclient/GetWeather.yaml

@@ -0,0 +1,29 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions using the tools provided.
+model:
+    options:
+        temperature: 0.9
+        topP: 0.95
+        allowMultipleToolCalls: true
+        chatToolMode: auto
+tools:
+  - kind: function
+    name: GetWeather
+    description: Get the weather for a given location.
+    bindings:
+      get_weather: get_weather
+    parameters:
+      properties:
+        location:
+          kind: string
+          description: The city and state, e.g. San Francisco, CA
+          required: true
+        unit:
+          kind: string
+          description: The unit of temperature. Possible values are 'celsius' and 'fahrenheit'.
+          required: false
+          enum:
+            - celsius
+            - fahrenheit

agent-samples/foundry/FoundryAgent.yaml

@@ -0,0 +1,22 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format.
+model:
+    id: gpt-4.1-mini
+    options:
+        temperature: 0.9
+        topP: 0.95
+    connection:
+        kind: Remote
+        endpoint: =Env.AZURE_FOUNDRY_PROJECT_ENDPOINT
+outputSchema:
+    properties:
+        language:
+            type: string
+            required: true
+            description: The language of the answer.
+        answer:
+            type: string
+            required: true
+            description: The answer text.

agent-samples/foundry/MicrosoftLearnAgent.yaml

@@ -0,0 +1,21 @@
+kind: Prompt
+name: MicrosoftLearnAgent
+description: Microsoft Learn Agent
+instructions: You answer questions by searching the Microsoft Learn content only.
+model:
+    id: =Env.AZURE_FOUNDRY_PROJECT_MODEL_ID
+    options:
+        temperature: 0.9
+        topP: 0.95
+    connection:
+        kind: remote
+        endpoint: =Env.AZURE_FOUNDRY_PROJECT_ENDPOINT
+tools:
+  - kind: mcp
+    name: microsoft_learn
+    description: Get information from Microsoft Learn.
+    url: https://learn.microsoft.com/api/mcp
+    approvalMode:
+      kind: never
+    allowedTools:
+      - microsoft_docs_search

agent-samples/foundry/PersistentAgent.yaml

@@ -0,0 +1,22 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions is the language specified by the user. You return your answers in a JSON format.
+model:
+    id: =Env.AZURE_FOUNDRY_PROJECT_MODEL_ID
+    options:
+        temperature: 0.9
+        topP: 0.95
+    connection:
+        kind: remote
+        endpoint: =Env.AZURE_FOUNDRY_PROJECT_ENDPOINT
+outputSchema:
+    properties:
+        language:
+            kind: string
+            required: true
+            description: The language of the answer.
+        answer:
+            kind: string
+            required: true
+            description: The answer text.

agent-samples/openai/OpenAI.yaml

@@ -0,0 +1,28 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions is the language specified by the user. You return your answers in a JSON format. You must include Chat as the type in your response.
+model:
+    id: =Env.OPENAI_MODEL
+    provider: OpenAI
+    apiType: Chat
+    options:
+        temperature: 0.9
+        topP: 0.95
+    connection:
+        kind: key
+        key: =Env.OPENAI_API_KEY
+outputSchema:
+    properties:
+        language:
+            kind: string
+            required: true
+            description: The language of the answer.
+        answer:
+            kind: string
+            required: true
+            description: The answer text.
+        type:
+            kind: string
+            required: true
+            description: The type of the response.

agent-samples/openai/OpenAIAssistants.yaml

@@ -0,0 +1,28 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Assistants as the type in your response.
+model:
+    id: gpt-4.1-mini
+    provider: OpenAI
+    apiType: Assistants
+    options:
+        temperature: 0.9
+        topP: 0.95
+    connection:
+        kind: ApiKey
+        key: =Env.OPENAI_API_KEY
+outputSchema:
+    properties:
+        language:
+            type: string
+            required: true
+            description: The language of the answer.
+        answer:
+            type: string
+            required: true
+            description: The answer text.
+        type:
+            type: string
+            required: true
+            description: The type of the response.

agent-samples/openai/OpenAIChat.yaml

@@ -0,0 +1,28 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Chat as the type in your response.
+model:
+    id: gpt-4.1-mini
+    provider: OpenAI
+    apiType: Chat
+    options:
+        temperature: 0.9
+        topP: 0.95
+    connection:
+        kind: ApiKey
+        key: =Env.OPENAI_API_KEY
+outputSchema:
+    properties:
+        language:
+            type: string
+            required: true
+            description: The language of the answer.
+        answer:
+            type: string
+            required: true
+            description: The answer text.
+        type:
+            type: string
+            required: true
+            description: The type of the response.

agent-samples/openai/OpenAIResponses.yaml

@@ -0,0 +1,28 @@
+kind: Prompt
+name: Assistant
+description: Helpful assistant
+instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format. You must include Responses as the type in your response.
+model:
+    id: gpt-4.1-mini
+    provider: OpenAI
+    apiType: Responses
+    options:
+        temperature: 0.9
+        topP: 0.95
+    connection:
+        kind: key
+        apiKey: =Env.OPENAI_APIKEY
+outputSchema:
+    properties:
+        language:
+            kind: string
+            required: true
+            description: The language of the answer.
+        answer:
+            kind: string
+            required: true
+            description: The answer text.
+        type:
+            kind: string
+            required: true
+            description: The type of the response.

docs/FAQS.md

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

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

@@ -64,7 +64,7 @@ Approaches observed from the compared SDKs:
 | AutoGen | **Approach 1** Separates messages into Agent-Agent (maps to Primary) and Internal (maps to Secondary) and these are returned as separate properties on the agent response object.  See [types of messages](https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/tutorial/messages.html#types-of-messages) and [Response](https://microsoft.github.io/autogen/stable/reference/python/autogen_agentchat.base.html#autogen_agentchat.base.Response) | **Approach 2** Returns a stream of internal events and the last item is a Response object. See [ChatAgent.on_messages_stream](https://microsoft.github.io/autogen/stable/reference/python/autogen_agentchat.base.html#autogen_agentchat.base.ChatAgent.on_messages_stream) |
 | OpenAI Agent SDK | **Approach 1** Separates new_items (Primary+Secondary) from final output (Primary) as separate properties on the [RunResult](https://github.com/openai/openai-agents-python/blob/main/src/agents/result.py#L39) | **Approach 1** Similar to non-streaming, has a way of streaming updates via a method on the response object which includes all data, and then a separate final output property on the response object which is populated only when the run is complete. See [RunResultStreaming](https://github.com/openai/openai-agents-python/blob/main/src/agents/result.py#L136) |
 | Google ADK | **Approach 2** [Emits events](https://google.github.io/adk-docs/runtime/#step-by-step-breakdown) with [FinalResponse](https://github.com/google/adk-java/blob/main/core/src/main/java/com/google/adk/events/Event.java#L232) true (Primary) / false (Secondary) and callers have to filter out those with false to get just the final response message | **Approach 2** Similar to non-streaming except [events](https://google.github.io/adk-docs/runtime/#streaming-vs-non-streaming-output-partialtrue) are emitted with [Partial](https://github.com/google/adk-java/blob/main/core/src/main/java/com/google/adk/events/Event.java#L133) true to indicate that they are streaming messages. A final non partial event is also emitted. |
-| AWS (Strands) | **Approach 3** Returns an [AgentResult](https://strandsagents.com/latest/api-reference/agent/#strands.agent.agent_result.AgentResult) (Primary) with messages and a reason for the run's completion. | **Approach 2** [Streams events](https://strandsagents.com/latest/api-reference/agent/#strands.agent.agent.Agent.stream_async) (Primary+Secondary) including, response text, current_tool_use, even data from "callbacks" (strands plugins) |
+| AWS (Strands) | **Approach 3** Returns an [AgentResult](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent_result/) (Primary) with messages and a reason for the run's completion. | **Approach 2** [Streams events](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent/#strands.agent.agent.Agent.stream_async) (Primary+Secondary) including, response text, current_tool_use, even data from "callbacks" (strands plugins) |
 | LangGraph | **Approach 2** A mixed list of all [messages](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) | **Approach 2** A mixed list of all [messages](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) |
 | Agno | **Combination of various approaches** Returns a [RunResponse](https://docs.agno.com/reference/agents/run-response) object with text content, messages (essentially chat history including inputs and instructions), reasoning and thinking text properties. Secondary events could potentially be extracted from messages. | **Approach 2** Returns [RunResponseEvent](https://docs.agno.com/reference/agents/run-response#runresponseevent-types-and-attributes) objects including tool call, memory update, etc, information, where the [RunResponseCompletedEvent](https://docs.agno.com/reference/agents/run-response#runresponsecompletedevent) has similar properties to RunResponse|
 | A2A | **Approach 3** Returns a [Task or Message](https://a2aproject.github.io/A2A/latest/specification/#71-messagesend) where the message is the final result (Primary) and task is a reference to a long running process. | **Approach 2** Returns a [stream](https://a2aproject.github.io/A2A/latest/specification/#72-messagestream) that contains task updates (Secondary) and a final message (Primary) |
@@ -163,8 +163,8 @@ foreach (var update in response.Messages)
 ### Option 2 Run: Container with Primary and Secondary Properties, RunStreaming: Stream of Primary + Secondary
 
 Run returns a new response type that has separate properties for the Primary Content and the Secondary Updates leading up to it.
-The Primary content is available in the `AgentRunResponse.Messages` property while Secondary updates are in a new `AgentRunResponse.Updates` property.
-`AgentRunResponse.Text` returns the Primary content text.
+The Primary content is available in the `AgentResponse.Messages` property while Secondary updates are in a new `AgentResponse.Updates` property.
+`AgentResponse.Text` returns the Primary content text.
 
 Since streaming would still need to return an `IAsyncEnumerable` of updates, the design would differ from non-streaming.
 With non-streaming Primary and Secondary content is split into separate lists, while with streaming it's combined in one stream.
@@ -232,24 +232,24 @@ await foreach (var update in responses)
 ```csharp
 class Agent
 {
-    public abstract Task<AgentRunResponse> RunAsync(
+    public abstract Task<AgentResponse> RunAsync(
         IReadOnlyCollection<ChatMessage> messages,
         AgentThread? thread = null,
         AgentRunOptions? options = null,
         CancellationToken cancellationToken = default);
 
-    public abstract IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(
+    public abstract IAsyncEnumerable<AgentResponseUpdate> RunStreamingAsync(
         IReadOnlyCollection<ChatMessage> messages,
         AgentThread? thread = null,
         AgentRunOptions? options = null,
         CancellationToken cancellationToken = default);
 }
 
-class AgentRunResponse : ChatResponse
+class AgentResponse : ChatResponse
 {
 }
 
-public class AgentRunResponseUpdate : ChatResponseUpdate
+public class AgentResponseUpdate : ChatResponseUpdate
 {
 }
 ```
@@ -265,20 +265,20 @@ The new types could also exclude properties that make less sense for agents, lik
 ```csharp
 class Agent
 {
-    public abstract Task<AgentRunResponse> RunAsync(
+    public abstract Task<AgentResponse> RunAsync(
         IReadOnlyCollection<ChatMessage> messages,
         AgentThread? thread = null,
         AgentRunOptions? options = null,
         CancellationToken cancellationToken = default);
 
-    public abstract IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(
+    public abstract IAsyncEnumerable<AgentResponseUpdate> RunStreamingAsync(
         IReadOnlyCollection<ChatMessage> messages,
         AgentThread? thread = null,
         AgentRunOptions? options = null,
         CancellationToken cancellationToken = default);
 }
 
-class AgentRunResponse // Compare with ChatResponse
+class AgentResponse // Compare with ChatResponse
 {
     public string Text { get; } // Aggregation of TextContent from messages.
 
@@ -294,12 +294,12 @@ class AgentRunResponse // Compare with ChatResponse
     public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
 }
 
-// Not Included in AgentRunResponse compared to ChatResponse
+// Not Included in AgentResponse compared to ChatResponse
 public ChatFinishReason? FinishReason { get; set; }
 public string? ConversationId { get; set; }
 public string? ModelId { get; set; }
 
-public class AgentRunResponseUpdate // Compare with ChatResponseUpdate
+public class AgentResponseUpdate // Compare with ChatResponseUpdate
 {
     public string Text { get; } // Aggregation of TextContent from Contents.
 
@@ -317,7 +317,7 @@ public class AgentRunResponseUpdate // Compare with ChatResponseUpdate
     public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
 }
 
-// Not Included in AgentRunResponseUpdate compared to ChatResponseUpdate
+// Not Included in AgentResponseUpdate compared to ChatResponseUpdate
 public ChatFinishReason? FinishReason { get; set; }
 public string? ConversationId { get; set; }
 public string? ModelId { get; set; }
@@ -360,7 +360,7 @@ public class ChatFinishReason
 ### Option 2: Add another property on responses for AgentRun
 
 ```csharp
-class AgentRunResponse
+class AgentResponse
 {
     ...
     public AgentRun RunReference { get; set; } // Reference to long running process
@@ -368,7 +368,7 @@ class AgentRunResponse
 }
 
 
-public class AgentRunResponseUpdate
+public class AgentResponseUpdate
 {
     ...
     public AgentRun RunReference { get; set; } // Reference to long running process
@@ -424,7 +424,7 @@ Note that where an agent doesn't support structured output, it may also be possi
 See [Structured Outputs Support](#structured-outputs-support) for a comparison on what other agent frameworks and protocols support.
 
 To support a good user experience for structured outputs, I'm proposing that we follow the pattern used by MEAI.
-We would add a generic version of `AgentRunResponse<T>`, that allows us to get the agent result already deserialized into our preferred type.
+We would add a generic version of `AgentResponse<T>`, that allows us to get the agent result already deserialized into our preferred type.
 This would be coupled with generic overload extension methods for Run that automatically builds a schema from the supplied type and updates
 the run options.
 
@@ -438,14 +438,14 @@ class Movie
     public int ReleaseYear { get; set; }
 }
 
-AgentRunResponse<Movie[]> response = agent.RunAsync<Movie[]>("What are the top 3 children's movies of the 80s.");
+AgentResponse<Movie[]> response = agent.RunAsync<Movie[]>("What are the top 3 children's movies of the 80s.");
 Movie[] movies = response.Result
 ```
 
 If we only support requesting a schema at agent creation time or where an agent has a built in schema, the following would be the preferred approach:
 
 ```csharp
-AgentRunResponse response = agent.RunAsync("What are the top 3 children's movies of the 80s.");
+AgentResponse response = agent.RunAsync("What are the top 3 children's movies of the 80s.");
 Movie[] movies = response.TryParseStructuredOutput<Movie[]>();
 ```
 
@@ -463,7 +463,7 @@ Option 2 chosen so that we can vary Agent responses independently of Chat Client
 ### StructuredOutputs Decision
 
 We will not support structured output per run request, but individual agents are free to allow this on the concrete implementation or at construction time.
-We will however add support for easily extracting a structured output type from the `AgentRunResponse`.
+We will however add support for easily extracting a structured output type from the `AgentResponse`.
 
 ## Addendum 1: AIContext Derived Types for different response types / Gap Analysis (Work in progress)
 
@@ -495,11 +495,11 @@ We need to decide what AIContent types, each agent response type will be mapped
 | SDK | Structured Outputs support |
 |-|-|
 | AutoGen | **Approach 1** Supports [configuring an agent](https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/tutorial/agents.html#structured-output) at agent creation. |
-| Google ADK | **Approach 1** Both [input and output shemas can be specified for LLM Agents](https://google.github.io/adk-docs/agents/llm-agents/#structuring-data-input_schema-output_schema-output_key) at construction time. This option is specific to this agent type and other agent types do not necessarily support |
-| AWS (Strands) | **Approach 2** Supports a special invocation method called [structured_output](https://strandsagents.com/latest/api-reference/agent/#strands.agent.agent.Agent.structured_output) |
+| Google ADK | **Approach 1** Both [input and output schemas can be specified for LLM Agents](https://google.github.io/adk-docs/agents/llm-agents/#structuring-data-input_schema-output_schema-output_key) at construction time. This option is specific to this agent type and other agent types do not necessarily support |
+| AWS (Strands) | **Approach 2** Supports a special invocation method called [structured_output](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent/#strands.agent.agent.Agent.structured_output) |
 | LangGraph | **Approach 1** Supports [configuring an agent](https://langchain-ai.github.io/langgraph/agents/agents/?h=structured#6-configure-structured-output) at agent construction time, and a [structured response](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) can be retrieved as a special property on the agent response |
 | Agno | **Approach 1** Supports [configuring an agent](https://docs.agno.com/examples/getting-started/structured-output) at agent construction time |
-| 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
@@ -508,8 +508,8 @@ We need to decide what AIContent types, each agent response type will be mapped
 |-|-|
 | AutoGen | Supports a [stop reason](https://microsoft.github.io/autogen/stable/reference/python/autogen_agentchat.base.html#autogen_agentchat.base.TaskResult.stop_reason) which is a freeform text string |
 | Google ADK | [No equivalent present](https://github.com/google/adk-python/blob/main/src/google/adk/events/event.py) |
-| 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. |
+| AWS (Strands) | Exposes a [stop_reason](https://strandsagents.com/latest/documentation/docs/api-reference/python/types/event_loop/#strands.types.event_loop.StopReason) property on the [AgentResult](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent_result/) 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 |
+| AgentResponse & AgentResponseUpdate | 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 AgentResponse
+{
+    ...
+
+    // A new property on AgentResponse 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 AgentResponse
+{
+    ...
+
+    // A new property on AgentResponse 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 AgentResponse
+{
+    ...
+
+    // A new property on AgentResponse 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 (AgentResponseUpdate, 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 (`AgentResponseUpdate` → AG-UI events) and client (AG-UI events → `AgentResponseUpdate`)
+
+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/decisions/0011-create-get-agent-api.md

@@ -0,0 +1,368 @@
+---
+status: proposed
+contact: dmytrostruk
+date: 2025-12-12
+deciders: dmytrostruk, markwallace-microsoft, eavanvalkenburg, giles17
+---
+
+# Create/Get Agent API
+
+## Context and Problem Statement
+
+There is a misalignment between the create/get agent API in the .NET and Python implementations.
+
+In .NET, the `CreateAIAgent` method can create either a local instance of an agent or a remote instance if the backend provider supports it. For remote agents, once the agent is created, you can retrieve an existing remote agent by using the `GetAIAgent` method. If a backend provider doesn't support remote agents, `CreateAIAgent` just initializes a new local agent instance and `GetAIAgent` is not available. There is also a `BuildAIAgent` method, which is an extension for the `ChatClientBuilder` class from `Microsoft.Extensions.AI`. It builds pipelines of `IChatClient` instances with an `IServiceProvider`. This functionality does not exist in Python, so `BuildAIAgent` is out of scope.
+
+In Python, there is only one `create_agent` method, which always creates a local instance of the agent. If the backend provider supports remote agents, the remote agent is created only on the first `agent.run()` invocation.
+
+Below is a short summary of different providers and their APIs in .NET:
+
+| Package | Method | Behavior | Python support |
+|---|---|---|---|
+| Microsoft.Agents.AI | `CreateAIAgent` (based on `IChatClient`) | Creates a local instance of `ChatClientAgent`. | Yes (`create_agent` in `BaseChatClient`). |
+| Microsoft.Agents.AI.Anthropic | `CreateAIAgent` (based on `IBetaService` and `IAnthropicClient`) | Creates a local instance of `ChatClientAgent`. | Yes (`AnthropicClient` inherits `BaseChatClient`, which exposes `create_agent`). |
+| Microsoft.Agents.AI.AzureAI (V2) | `GetAIAgent` (based on `AIProjectClient` with `AgentReference`) | Creates a local instance of `ChatClientAgent`. | Partial (Python uses `create_agent` from `BaseChatClient`). |
+| Microsoft.Agents.AI.AzureAI (V2) | `GetAIAgent`/`GetAIAgentAsync` (with `Name`/`ChatClientAgentOptions`) | Fetches `AgentRecord` via HTTP, then creates a local `ChatClientAgent` instance. | No |
+| Microsoft.Agents.AI.AzureAI (V2) | `CreateAIAgent`/`CreateAIAgentAsync` (based on `AIProjectClient`) | Creates a remote agent first, then wraps it into a local `ChatClientAgent` instance. | No |
+| Microsoft.Agents.AI.AzureAI.Persistent (V1) | `GetAIAgent` (based on `PersistentAgentsClient` with `PersistentAgent`) | Creates a local instance of `ChatClientAgent`. | Partial (Python uses `create_agent` from `BaseChatClient`). |
+| Microsoft.Agents.AI.AzureAI.Persistent (V1) | `GetAIAgent`/`GetAIAgentAsync` (with `AgentId`) | Fetches `PersistentAgent` via HTTP, then creates a local `ChatClientAgent` instance. | No |
+| Microsoft.Agents.AI.AzureAI.Persistent (V1) | `CreateAIAgent`/`CreateAIAgentAsync` | Creates a remote agent first, then wraps it into a local `ChatClientAgent` instance. | No |
+| Microsoft.Agents.AI.OpenAI | `GetAIAgent` (based on `AssistantClient` with `Assistant`) | Creates a local instance of `ChatClientAgent`. | Partial (Python uses `create_agent` from `BaseChatClient`). |
+| Microsoft.Agents.AI.OpenAI | `GetAIAgent`/`GetAIAgentAsync` (with `AgentId`) | Fetches `Assistant` via HTTP, then creates a local `ChatClientAgent` instance. | No |
+| Microsoft.Agents.AI.OpenAI | `CreateAIAgent`/`CreateAIAgentAsync` (based on `AssistantClient`) | Creates a remote agent first, then wraps it into a local `ChatClientAgent` instance. | No |
+| Microsoft.Agents.AI.OpenAI | `CreateAIAgent` (based on `ChatClient`) | Creates a local instance of `ChatClientAgent`. | Yes (`create_agent` in `BaseChatClient`). |
+| Microsoft.Agents.AI.OpenAI | `CreateAIAgent` (based on `OpenAIResponseClient`) | Creates a local instance of `ChatClientAgent`. | Yes (`create_agent` in `BaseChatClient`). |
+
+Another difference between Python and .NET implementation is that in .NET `CreateAIAgent`/`GetAIAgent` methods are implemented as extension methods based on underlying SDK client, like `AIProjectClient` from Azure AI or `AssistantClient` from OpenAI:
+
+```csharp
+// Definition
+public static ChatClientAgent CreateAIAgent(
+    this AIProjectClient aiProjectClient,
+    string name,
+    string model,
+    string instructions,
+    string? description = null,
+    IList<AITool>? tools = null,
+    Func<IChatClient, IChatClient>? clientFactory = null,
+    IServiceProvider? services = null,
+    CancellationToken cancellationToken = default)
+{ }
+
+// Usage
+AIProjectClient aiProjectClient = new(new Uri(endpoint), new AzureCliCredential()); // Initialization of underlying SDK client
+
+var newAgent = await aiProjectClient.CreateAIAgentAsync(name: AgentName, model: deploymentName, instructions: AgentInstructions, tools: [tool]); // ChatClientAgent creation from underlying SDK client
+
+// Alternative usage (same as extension method, just explicit syntax)
+var newAgent = await AzureAIProjectChatClientExtensions.CreateAIAgentAsync(
+    aiProjectClient,
+    name: AgentName,
+    model: deploymentName,
+    instructions: AgentInstructions,
+    tools: [tool]);
+```
+
+Python doesn't support extension methods. Currently `create_agent` method is defined on `BaseChatClient`, but this method only creates a local instance of `ChatAgent` and it can't create remote agents for providers that support it for a couple of reasons:
+
+- It's defined as non-async.
+- `BaseChatClient` implementation is stateful for providers like Azure AI or OpenAI Assistants. The implementation stores agent/assistant metadata like `AgentId` and `AgentName`, so currently it's not possible to create different instances of `ChatAgent` from a single `BaseChatClient` in case if the implementation is stateful.
+
+## Decision Drivers
+
+- API should be aligned between .NET and Python.
+- API should be intuitive and consistent between backend providers in .NET and Python.
+
+## Considered Options
+
+Add missing implementations on the Python side. This should include the following:
+
+### agent-framework-azure-ai (both V1 and V2)
+
+- Add a `get_agent` method that accepts an underlying SDK agent instance and creates a local instance of `ChatAgent`.
+- Add a `get_agent` method that accepts an agent identifier, performs an additional HTTP request to fetch agent data, and then creates a local instance of `ChatAgent`.
+- Override the `create_agent` method from `BaseChatClient` to create a remote agent instance and wrap it into a local `ChatAgent`.
+
+.NET:
+
+```csharp
+var agent1 = new AIProjectClient(...).GetAIAgent(agentInstanceFromSdkType); // Creates a local ChatClientAgent instance from Azure.AI.Projects.OpenAI.AgentReference 
+var agent2 = new AIProjectClient(...).GetAIAgent(agentName); // Fetches agent data, creates a local ChatClientAgent instance
+var agent3 = new AIProjectClient(...).CreateAIAgent(...); // Creates a remote agent, returns a local ChatClientAgent instance
+```
+
+### agent-framework-core (OpenAI Assistants)
+
+- Add a `get_agent` method that accepts an underlying SDK agent instance and creates a local instance of `ChatAgent`.
+- Add a `get_agent` method that accepts an agent name, performs an additional HTTP request to fetch agent data, and then creates a local instance of `ChatAgent`.
+- Override the `create_agent` method from `BaseChatClient` to create a remote agent instance and wrap it into a local `ChatAgent`.
+
+.NET:
+
+```csharp
+var agent1 = new AssistantClient(...).GetAIAgent(agentInstanceFromSdkType); // Creates a local ChatClientAgent instance from OpenAI.Assistants.Assistant
+var agent2 = new AssistantClient(...).GetAIAgent(agentId); // Fetches agent data, creates a local ChatClientAgent instance
+var agent3 = new AssistantClient(...).CreateAIAgent(...); // Creates a remote agent, returns a local ChatClientAgent instance
+```
+
+### Possible Python implementations
+
+Methods like `create_agent` and `get_agent` should be implemented separately or defined on some stateless component that will allow to create multiple agents from the same instance/place.
+
+Possible options:
+
+#### Option 1: Module-level functions
+
+Implement free functions in the provider package that accept the underlying SDK client as the first argument (similar to .NET extension methods, but expressed in Python).
+
+Example:
+
+```python
+from agent_framework.azure import create_agent, get_agent
+
+ai_project_client = AIProjectClient(...)
+
+# Creates a remote agent first, then returns a local ChatAgent wrapper
+created_agent = await create_agent(
+    ai_project_client,
+    name="",
+    instructions="",
+    tools=[tool],
+)
+
+# Gets an existing remote agent and returns a local ChatAgent wrapper
+first_agent = await get_agent(ai_project_client, agent_id=agent_id)
+
+# Wraps an SDK agent instance (no extra HTTP call)
+second_agent = get_agent(ai_project_client, agent_reference)
+```
+
+Pros:
+
+- Naturally supports async `create_agent` / `get_agent`.
+- Supports multiple agents per SDK client.
+- Closest conceptual match to .NET extension methods while staying Pythonic.
+
+Cons:
+
+- Discoverability is lower (users need to know where the functions live).
+- Verbose when creating multiple agents (client must be passed every time):
+
+  ```python
+  agent1 = await azure_agents.create_agent(client, name="Agent1", ...)
+  agent2 = await azure_agents.create_agent(client, name="Agent2", ...)
+  ```
+
+#### Option 2: Provider object
+
+Introduce a dedicated provider type that is constructed from the underlying SDK client, and exposes async `create_agent` / `get_agent` methods.
+
+Example:
+
+```python
+from agent_framework.azure import AzureAIAgentProvider
+
+ai_project_client = AIProjectClient(...)
+provider = AzureAIAgentProvider(ai_project_client)
+
+agent = await provider.create_agent(
+    name="",
+    instructions="",
+    tools=[tool],
+)
+
+agent = await provider.get_agent(agent_id=agent_id)
+agent = provider.get_agent(agent_reference=agent_reference)
+```
+
+Pros:
+
+- High discoverability and clear grouping of related behavior.
+- Keeps SDK clients unchanged and supports multiple agents per SDK client.
+- Concise when creating multiple agents (client passed once):
+
+  ```python
+  provider = AzureAIAgentProvider(ai_project_client)
+  agent1 = await provider.create_agent(name="Agent1", ...)
+  agent2 = await provider.create_agent(name="Agent2", ...)
+  ```
+
+Cons:
+
+- Adds a new public concept/type for users to learn.
+
+#### Option 3: Inheritance (SDK client subclass)
+
+Create a subclass of the underlying SDK client and add `create_agent` / `get_agent` methods.
+
+Example:
+
+```python
+class ExtendedAIProjectClient(AIProjectClient):
+    async def create_agent(self, *, name: str, model: str, instructions: str, **kwargs) -> ChatAgent:
+        ...
+
+    async def get_agent(self, *, agent_id: str | None = None, sdk_agent=None, **kwargs) -> ChatAgent:
+        ...
+
+client = ExtendedAIProjectClient(...)
+agent = await client.create_agent(name="", instructions="")
+```
+
+Pros:
+
+- Discoverable and ergonomic call sites.
+- Mirrors the .NET “methods on the client” feeling.
+
+Cons:
+
+- Many SDK clients are not designed for inheritance; SDK upgrades can break subclasses.
+- Users must opt into subclass everywhere.
+- Typing/initialization can be tricky if the SDK client has non-trivial constructors.
+
+#### Option 4: Monkey patching
+
+Attach `create_agent` / `get_agent` methods to an SDK client class (or instance) at runtime.
+
+Example:
+
+```python
+def _create_agent(self, *, name: str, model: str, instructions: str, **kwargs) -> ChatAgent:
+    ...
+
+AIProjectClient.create_agent = _create_agent  # monkey patch
+```
+
+Pros:
+
+- Produces “extension method-like” call sites without wrappers or subclasses.
+
+Cons:
+
+- Fragile across SDK updates and difficult to type-check.
+- Surprising behavior (global side effects), potential conflicts across packages.
+- Harder to support/debug, especially in larger apps and test suites.
+
+## Decision Outcome
+
+Implement `create_agent`/`get_agent`/`as_agent` API via **Option 2: Provider object**.
+
+### Rationale
+
+| Aspect | Option 1 (Functions) | Option 2 (Provider) |
+|--------|----------------------|---------------------|
+| Multiple implementations | One package may contain V1, V2, and other agent types. Function names like `create_agent` become ambiguous - which agent type does it create? | Each provider class is explicit: `AzureAIAgentsProvider` vs `AzureAIProjectAgentProvider` |
+| Discoverability | Users must know to import specific functions from the package | IDE autocomplete on provider instance shows all available methods |
+| Client reuse | SDK client must be passed to every function call: `create_agent(client, ...)`, `get_agent(client, ...)` | SDK client passed once at construction: `provider = Provider(client)` |
+
+**Option 1 example:**
+```python
+from agent_framework.azure import create_agent, get_agent
+agent1 = await create_agent(client, name="Agent1", ...)  # Which agent type, V1 or V2?
+agent2 = await create_agent(client, name="Agent2", ...)  # Repetitive client passing
+```
+
+**Option 2 example:**
+```python
+from agent_framework.azure import AzureAIProjectAgentProvider
+provider = AzureAIProjectAgentProvider(client)  # Clear which service, client passed once
+agent1 = await provider.create_agent(name="Agent1", ...)
+agent2 = await provider.create_agent(name="Agent2", ...)
+```
+
+### Method Naming
+
+| Operation | Python | .NET | Async |
+|-----------|--------|------|-------|
+| Create on service | `create_agent()` | `CreateAIAgent()` | Yes |
+| Get from service | `get_agent(id=...)` | `GetAIAgent(agentId)` | Yes |
+| Wrap SDK object | `as_agent(reference)` | `AsAIAgent(agentInstance)` | No |
+
+The method names (`create_agent`, `get_agent`) do not explicitly mention "service" or "remote" because:
+- In Python, the provider class name explicitly identifies the service (`AzureAIAgentsProvider`, `OpenAIAssistantProvider`), making additional qualifiers in method names redundant.
+- In .NET, these are extension methods on `AIProjectClient` or `AssistantClient`, which already imply service operations.
+
+### Provider Class Naming
+
+| Package | Provider Class | SDK Client | Service |
+|---------|---------------|------------|---------|
+| `agent_framework.azure` | `AzureAIProjectAgentProvider` | `AIProjectClient` | Azure AI Agent Service, based on Responses API (V2) |
+| `agent_framework.azure` | `AzureAIAgentsProvider` | `AgentsClient` | Azure AI Agent Service (V1) |
+| `agent_framework.openai` | `OpenAIAssistantProvider` | `AsyncOpenAI` | OpenAI Assistants API |
+
+> **Note:** Azure AI naming is temporary. Final naming will be updated according to Azure AI / Microsoft Foundry renaming decisions.
+
+### Usage Examples
+
+#### Azure AI Agent Service V2 (based on Responses API)
+
+```python
+from agent_framework.azure import AzureAIProjectAgentProvider
+from azure.ai.projects import AIProjectClient
+
+client = AIProjectClient(endpoint, credential)
+provider = AzureAIProjectAgentProvider(client)
+
+# Create new agent on service
+agent = await provider.create_agent(name="MyAgent", model="gpt-4", instructions="...")
+
+# Get existing agent by name
+agent = await provider.get_agent(agent_name="MyAgent")
+
+# Wrap already-fetched SDK object (no HTTP calls)
+agent_ref = await client.agents.get("MyAgent")
+agent = provider.as_agent(agent_ref)
+```
+
+#### Azure AI Persistent Agents V1
+
+```python
+from agent_framework.azure import AzureAIAgentsProvider
+from azure.ai.agents import AgentsClient
+
+client = AgentsClient(endpoint, credential)
+provider = AzureAIAgentsProvider(client)
+
+agent = await provider.create_agent(name="MyAgent", model="gpt-4", instructions="...")
+agent = await provider.get_agent(agent_id="persistent-agent-456")
+agent = provider.as_agent(persistent_agent)
+```
+
+#### OpenAI Assistants
+
+```python
+from agent_framework.openai import OpenAIAssistantProvider
+from openai import OpenAI
+
+client = OpenAI()
+provider = OpenAIAssistantProvider(client)
+
+agent = await provider.create_agent(name="MyAssistant", model="gpt-4", instructions="...")
+agent = await provider.get_agent(assistant_id="asst_123")
+agent = provider.as_agent(assistant)
+```
+
+#### Local-Only Agents (No Provider)
+
+Current method `create_agent` (python) / `CreateAIAgent` (.NET) can be renamed to `as_agent` (python) / `AsAIAgent` (.NET) to emphasize the conversion logic rather than creation/initialization logic and to avoid collision with `create_agent` method for remote calls.
+
+```python
+from agent_framework import ChatAgent
+from agent_framework.openai import OpenAIChatClient
+
+# Convert chat client to ChatAgent (no remote service involved)
+client = OpenAIChatClient(model="gpt-4")
+agent = client.as_agent(name="LocalAgent", instructions="...") # instead of create_agent
+```
+
+### Adding New Agent Types
+
+Python:
+
+1. Create provider class in appropriate package.
+2. Implement `create_agent`, `get_agent`, `as_agent` as applicable.
+
+.NET:
+
+1. Create static class for extension methods.
+2. Implement `CreateAIAgentAsync`, `GetAIAgentAsync`, `AsAIAgent` as applicable.

docs/decisions/0012-python-typeddict-options.md

@@ -0,0 +1,129 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: proposed
+contact: eavanvalkenburg
+date: 2026-01-08
+deciders: eavanvalkenburg, markwallace-microsoft,  sphenry, alliscode, johanst, brettcannon
+consulted: taochenosu, moonbox3, dmytrostruk, giles17
+---
+
+# Leveraging TypedDict and Generic Options in Python Chat Clients
+
+## Context and Problem Statement
+
+The Agent Framework Python SDK provides multiple chat client implementations for different providers (OpenAI, Anthropic, Azure AI, Bedrock, Ollama, etc.). Each provider has unique configuration options beyond the common parameters defined in `ChatOptions`. Currently, developers using these clients lack type safety and IDE autocompletion for provider-specific options, leading to runtime errors and a poor developer experience.
+
+How can we provide type-safe, discoverable options for each chat client while maintaining a consistent API across all implementations?
+
+## Decision Drivers
+
+- **Type Safety**: Developers should get compile-time/static analysis errors when using invalid options
+- **IDE Support**: Full autocompletion and inline documentation for all available options
+- **Extensibility**: Users should be able to define custom options that extend provider-specific options
+- **Consistency**: All chat clients should follow the same pattern for options handling
+- **Provider Flexibility**: Each provider can expose its unique options without affecting the common interface
+
+## Considered Options
+
+- **Option 1: Status Quo - Class `ChatOptions` with `**kwargs`**
+- **Option 2: TypedDict with Generic Type Parameters**
+
+### Option 1: Status Quo - Class `ChatOptions` with `**kwargs`
+
+The current approach uses a base `ChatOptions` Class with common parameters, and provider-specific options are passed via `**kwargs` or loosely typed dictionaries.
+
+```python
+# Current usage - no type safety for provider-specific options
+response = await client.get_response(
+    messages=messages,
+    temperature=0.7,
+    top_k=40,
+    random=42, # No validation
+)
+```
+
+**Pros:**
+- Simple implementation
+- Maximum flexibility
+
+**Cons:**
+- No type checking for provider-specific options
+- No IDE autocompletion for available options
+- Runtime errors for typos or invalid options
+- Documentation must be consulted for each provider
+
+### Option 2: TypedDict with Generic Type Parameters (Chosen)
+
+Each chat client is parameterized with a TypeVar bound to a provider-specific `TypedDict` that extends `ChatOptions`. This enables full type safety and IDE support.
+
+```python
+# Provider-specific TypedDict
+class AnthropicChatOptions(ChatOptions, total=False):
+    """Anthropic-specific chat options."""
+    top_k: int
+    thinking: ThinkingConfig
+    # ... other Anthropic-specific options
+
+# Generic chat client
+class AnthropicChatClient(ChatClientBase[TAnthropicChatOptions]):
+    ...
+
+client = AnthropicChatClient(...)
+
+# Usage with full type safety
+response = await client.get_response(
+    messages=messages,
+    options={
+        "temperature": 0.7,
+        "top_k": 40,
+        "random": 42,  # fails type checking and IDE would flag this
+    }
+)
+
+# Users can extend for custom options
+class MyAnthropicOptions(AnthropicChatOptions, total=False):
+    custom_field: str
+
+
+client = AnthropicChatClient[MyAnthropicOptions](...)
+
+# Usage of custom options with full type safety
+response = await client.get_response(
+    messages=messages,
+    options={
+        "temperature": 0.7,
+        "top_k": 40,
+        "custom_field": "value",
+    }
+)
+
+```
+
+**Pros:**
+- Full type safety with static analysis
+- IDE autocompletion for all options
+- Compile-time error detection
+- Self-documenting through type hints
+- Users can extend options for their specific needs or advances in models
+
+**Cons:**
+- More complex implementation
+- Some type: ignore comments needed for TypedDict field overrides
+- Minor: Requires TypeVar with default (Python 3.13+ or typing_extensions)
+
+> [NOTE!]
+> In .NET this is already achieved through overloads on the `GetResponseAsync` method for each provider-specific options class, e.g., `AnthropicChatOptions`, `OpenAIChatOptions`, etc. So this does not apply to .NET.
+
+### Implementation Details
+
+1. **Base Protocol**: `ChatClientProtocol[TOptions]` is generic over options type, with default set to `ChatOptions` (the new TypedDict)
+2. **Provider TypedDicts**: Each provider defines its options extending `ChatOptions`
+    They can even override fields with type=None to indicate they are not supported.
+3. **TypeVar Pattern**: `TProviderOptions = TypeVar("TProviderOptions", bound=TypedDict, default=ProviderChatOptions, contravariant=True)`
+4. **Option Translation**: Common options are kept in place,and explicitly documented in the Options class how they are used. (e.g., `user` → `metadata.user_id`) in `_prepare_options` (for Anthropic) to preserve easy use of common options.
+
+## Decision Outcome
+
+Chosen option: **"Option 2: TypedDict with Generic Type Parameters"**, because it provides full type safety, excellent IDE support with autocompletion, and allows users to extend provider-specific options for their use cases. Extended this Generic to ChatAgents in order to also properly type the options used in agent construction and run methods.
+
+See [typed_options.py](../../python/samples/concepts/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions.

docs/decisions/0013-python-get-response-simplification.md

@@ -0,0 +1,258 @@
+---
+status: Accepted
+contact: eavanvalkenburg
+date: 2026-01-06
+deciders: markwallace-microsoft, dmytrostruk, taochenosu, alliscode, moonbox3, sphenry
+consulted: sergeymenshykh, rbarreto, dmytrostruk, westey-m
+informed:
+---
+
+# Simplify Python Get Response API into a single method
+
+## Context and Problem Statement
+
+Currently chat clients must implement two separate methods to get responses, one for streaming and one for non-streaming. This adds complexity to the client implementations and increases the maintenance burden. This was likely done because the .NET version cannot do proper typing with a single method, in Python this is possible and this for instance is also how the OpenAI python client works, this would then also make it simpler to work with the Python version because there is only one method to learn about instead of two.
+
+## Implications of this change
+
+### Current Architecture Overview
+
+The current design has **two separate methods** at each layer:
+
+| Layer | Non-streaming | Streaming |
+|-------|---------------|-----------|
+| **Protocol** | `get_response()` → `ChatResponse` | `get_streaming_response()` → `AsyncIterable[ChatResponseUpdate]` |
+| **BaseChatClient** | `get_response()` (public) | `get_streaming_response()` (public) |
+| **Implementation** | `_inner_get_response()` (private) | `_inner_get_streaming_response()` (private) |
+
+### Key Usage Areas Identified
+
+#### 1. **ChatAgent** (_agents.py)
+- `run()` → calls `self.chat_client.get_response()`
+- `run_stream()` → calls `self.chat_client.get_streaming_response()`
+
+These are parallel methods on the agent, so consolidating the client methods would **not break** the agent API. You could keep `agent.run()` and `agent.run_stream()` unchanged while internally calling `get_response(stream=True/False)`.
+
+#### 2. **Function Invocation Decorator** (_tools.py)
+This is **the most impacted area**. Currently:
+- `_handle_function_calls_response()` decorates `get_response`
+- `_handle_function_calls_streaming_response()` decorates `get_streaming_response`
+- The `use_function_invocation` class decorator wraps **both methods separately**
+
+**Impact**: The decorator logic is almost identical (~200 lines each) with small differences:
+- Non-streaming collects response, returns it
+- Streaming yields updates, returns async iterable
+
+With a unified method, you'd need **one decorator** that:
+- Checks the `stream` parameter
+- Uses `@overload` to determine return type
+- Handles both paths with conditional logic
+- The new decorator could be applied just on the method, instead of the whole class.
+
+This would **reduce code duplication** but add complexity to a single function.
+
+#### 3. **Observability/Instrumentation** (observability.py)
+Same pattern as function invocation:
+- `_trace_get_response()` wraps `get_response`
+- `_trace_get_streaming_response()` wraps `get_streaming_response`
+- `use_instrumentation` decorator applies both
+
+**Impact**: Would need consolidation into a single tracing wrapper.
+
+#### 4. **Chat Middleware** (_middleware.py)
+The `use_chat_middleware` decorator also wraps both methods separately with similar logic.
+
+#### 5. **AG-UI Client** (_client.py)
+Wraps both methods to unwrap server function calls:
+```python
+original_get_streaming_response = chat_client.get_streaming_response
+original_get_response = chat_client.get_response
+```
+
+#### 6. **Provider Implementations** (all subpackages)
+All subclasses implement both `_inner_*` methods, except:
+- OpenAI Assistants Client (and similar clients, such as Foundry Agents V1) - it implements `_inner_get_response` by calling `_inner_get_streaming_response`
+
+### Implications of Consolidation
+
+| Aspect | Impact |
+|--------|--------|
+| **Type Safety** | Overloads work well: `@overload` with `Literal[True]` → `AsyncIterable`, `Literal[False]` → `ChatResponse`. Runtime return type based on `stream` param. |
+| **Breaking Change** | **Major breaking change** for anyone implementing custom chat clients. They'd need to update from 2 methods to 1 (or 2 inner methods to 1). |
+| **Decorator Complexity** | All 3 decorator systems (function invocation, middleware, observability) would need refactoring to handle both paths in one wrapper. |
+| **Code Reduction** | Significant reduction in _tools.py (~200 lines of near-duplicate code) and other decorators. |
+| **Samples/Tests** | Many samples call `get_streaming_response()` directly - would need updates. |
+| **Protocol Simplification** | `ChatClientProtocol` goes from 2 methods + 1 property to 1 method + 1 property. |
+
+### Recommendation
+
+The consolidation makes sense architecturally, but consider:
+
+1. **The overload pattern with `stream: bool`** works well in Python typing:
+   ```python
+   @overload
+   async def get_response(self, messages, *, stream: Literal[True] = True, ...) -> AsyncIterable[ChatResponseUpdate]: ...
+   @overload
+   async def get_response(self, messages, *, stream: Literal[False] = False, ...) -> ChatResponse: ...
+   ```
+
+2. **The decorator complexity** is the biggest concern. The current approach of separate decorators for separate methods is cleaner than conditional logic inside one wrapper.
+
+## Decision Drivers
+
+- Reduce code needed to implement a Chat Client, simplify the public API for chat clients
+- Reduce code duplication in decorators and middleware
+- Maintain type safety and clarity in method signatures
+
+## Considered Options
+
+1. Status quo: Keep separate methods for streaming and non-streaming
+2. Consolidate into a single `get_response` method with a `stream` parameter
+3. Option 2 plus merging `agent.run` and `agent.run_stream` into a single method with a `stream` parameter as well
+
+## Option 1: Status Quo
+- Good: Clear separation of streaming vs non-streaming logic
+- Good: Aligned with .NET design, although it is already `run` for Python and `RunAsync` for .NET
+- Bad: Code duplication in decorators and middleware
+- Bad: More complex client implementations
+
+## Option 2: Consolidate into Single Method
+- Good: Simplified public API for chat clients
+- Good: Reduced code duplication in decorators
+- Good: Smaller API footprint for users to get familiar with
+- Good: People using OpenAI directly already expect this pattern
+- Bad: Increased complexity in decorators and middleware
+- Bad: Less alignment with .NET design (`get_response(stream=True)` vs `GetStreamingResponseAsync`)
+
+## Option 3: Consolidate + Merge Agent and Workflow Methods
+- Good: Further simplifies agent and workflow implementation
+- Good: Single method for all chat interactions
+- Good: Smaller API footprint for users to get familiar with
+- Good: People using OpenAI directly already expect this pattern
+- Good: Workflows internally already use a single method (_run_workflow_with_tracing), so would eliminate public API duplication as well, with hardly any code changes
+- Bad: More breaking changes for agent users
+- Bad: Increased complexity in agent implementation
+- Bad: More extensive misalignment with .NET design (`run(stream=True)` vs `RunStreamingAsync` in addition to `get_response` change)
+
+## Misc
+
+Smaller questions to consider:
+- Should default be `stream=False` or `stream=True`? (Current is False)
+    - Default to `False` makes it simpler for new users, as non-streaming is easier to handle.
+    - Default to `False` aligns with existing behavior.
+    - Streaming tends to be faster, so defaulting to `True` could improve performance for common use cases.
+    - Should this differ between ChatClient, Agent and Workflows? (e.g., Agent and Workflow defaults to streaming, ChatClient to non-streaming)
+
+## Decision Outcome
+
+Chosen Option: **Option 3: Consolidate + Merge Agent and Workflow Methods**
+
+Since this is the most pythonic option and it reduces the API surface and code duplication the most, we will go with this option.
+We will keep the default of `stream=False` for all methods to maintain backward compatibility and simplicity for new users.
+
+# Appendix
+## Code Samples for Consolidated Method
+
+### Python - Option 3: Direct ChatClient + Agent with Single Method
+
+```python
+# Copyright (c) Microsoft. All rights reserved.
+
+import asyncio
+from random import randint
+from typing import Annotated
+
+from agent_framework import ChatAgent
+from agent_framework.openai import OpenAIChatClient
+from pydantic import Field
+
+
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location."""
+    conditions = ["sunny", "cloudy", "rainy", "stormy"]
+    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."
+
+
+async def main() -> None:
+    # Example 1: Direct ChatClient usage with single method
+    client = OpenAIChatClient()
+    message = "What's the weather in Amsterdam and in Paris?"
+
+    # Non-streaming usage
+    print(f"User: {message}")
+    response = await client.get_response(message, tools=get_weather)
+    print(f"Assistant: {response.text}")
+
+    # Streaming usage - same method, different parameter
+    print(f"\nUser: {message}")
+    print("Assistant: ", end="")
+    async for chunk in client.get_response(message, tools=get_weather, stream=True):
+        if chunk.text:
+            print(chunk.text, end="")
+    print("")
+
+    # Example 2: Agent usage with single method
+    agent = ChatAgent(
+        chat_client=client,
+        tools=get_weather,
+        name="WeatherAgent",
+        instructions="You are a weather assistant.",
+    )
+    thread = agent.get_new_thread()
+
+    # Non-streaming agent
+    print(f"\nUser: {message}")
+    result = await agent.run(message, thread=thread) # default would be stream=False
+    print(f"{agent.name}: {result.text}")
+
+    # Streaming agent - same method, different parameter
+    print(f"\nUser: {message}")
+    print(f"{agent.name}: ", end="")
+    async for update in agent.run(message, thread=thread, stream=True):
+        if update.text:
+            print(update.text, end="")
+    print("")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### .NET - Current pattern for comparison
+
+```csharp
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI.Chat;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
+    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new AzureCliCredential())
+    .GetChatClient(deploymentName)
+    .CreateAIAgent(
+        instructions: "You are good at telling jokes about pirates.",
+        name: "PirateJoker");
+
+// Non-streaming: Returns a string directly
+Console.WriteLine("=== Non-streaming ===");
+string result = await agent.RunAsync("Tell me a joke about a pirate.");
+Console.WriteLine(result);
+
+// Streaming: Returns IAsyncEnumerable<AgentUpdate>
+Console.WriteLine("\n=== Streaming ===");
+await foreach (AgentUpdate update in agent.RunStreamingAsync("Tell me a joke about a pirate."))
+{
+    Console.Write(update);
+}
+Console.WriteLine();
+
+```

docs/decisions/0014-feature-collections.md

@@ -0,0 +1,423 @@
+---
+status: accepted
+contact: westey-m
+date: 2025-01-21
+deciders: sergeymenshykh, markwallace, rbarreto, westey-m, stephentoub
+consulted: reubenbond
+informed:
+---
+
+# Feature Collections
+
+## Context and Problem Statement
+
+When using agents, we often have cases where we want to pass some arbitrary services or data to an agent or some component in the agent execution stack.
+These services or data are not necessarily known at compile time and can vary by the agent stack that the user has built.
+E.g., there may be an agent decorator or chat client decorator that was added to the stack by the user, and an arbitrary payload needs to be passed to that decorator.
+
+Since these payloads are related to components that are not integral parts of the agent framework, they cannot be added as strongly typed settings to the agent run options.
+However, the payloads could be added to the agent run options as loosely typed 'features', that can be retrieved as needed.
+
+In some cases certain classes of agents may support the same capability, but not all agents do.
+Having the configuration for such a capability on the main abstraction would advertise the functionality to all users, even if their chosen agent does not support it.
+The user may type test for certain agent types, and call overloads on the appropriate agent types, with the strongly typed configuration.
+Having a feature collection though, would be an alternative way of passing such configuration, without needing to type check the agent type.
+All agents that support the functionality would be able to check for the configuration and use it, simplifying the user code.
+If the agent does not support the capability, that configuration would be ignored.
+
+### Sample Scenario 1 - Per Run ChatMessageStore Override for hosting Libraries
+
+We are building an agent hosting library, that can host any agent built using the agent framework.
+Where an agent is not built on a service that uses in-service chat history storage, the hosting library wants to force the agent to use
+the hosting library's chat history storage implementation.
+This chat history storage implementation may be specifically tailored to the type of protocol that the hosting library uses, e.g. conversation id based storage or response id based storage.
+The hosting library does not know what type of agent it is hosting, so it cannot provide a strongly typed parameter on the agent.
+Instead, it adds the chat history storage implementation to a feature collection, and if the agent supports custom chat history storage, it retrieves the implementation from the feature collection and uses it.
+
+```csharp
+// Pseudo-code for an agent hosting library that supports conversation id based hosting.
+public async Task<string> HandleConversationsBasedRequestAsync(AIAgent agent, string conversationId, string userInput)
+{
+    var thread = await this._threadStore.GetOrCreateThread(conversationId);
+
+    // The hosting library can set a per-run chat message store via Features that only applies for that run.
+    // This message store will load and save messages under the conversation id provided.
+    ConversationsChatMessageStore messageStore = new(this._dbClient, conversationId);
+    var response = await agent.RunAsync(
+        userInput,
+        thread,
+        options: new AgentRunOptions()
+        {
+            Features = new AgentFeatureCollection().WithFeature<ChatMessageStore>(messageStore)
+        });
+
+    await this._threadStore.SaveThreadAsync(conversationId, thread);
+    return response.Text;
+}
+
+// Pseudo-code for an agent hosting library that supports response id based hosting.
+public async Task<(string responseMessage, string responseId)> HandleResponseIdBasedRequestAsync(AIAgent agent, string previousResponseId, string userInput)
+{
+    var thread = await this._threadStore.GetOrCreateThreadAsync(previousResponseId);
+
+    // The hosting library can set a per-run chat message store via Features that only applies for that run.
+    // This message store will buffer newly added messages until explicitly saved after the run.
+    ResponsesChatMessageStore messageStore = new(this._dbClient, previousResponseId);
+
+    var response = await agent.RunAsync(
+        userInput,
+        thread,
+        options: new AgentRunOptions()
+        {
+            Features = new AgentFeatureCollection().WithFeature<ChatMessageStore>(messageStore)
+        });
+
+    // Since the message store may not actually have been used at all (if the agent's underlying chat client requires service-based chat history storage),
+    // we may not have anything to save back to the database.
+    // We still want to generate a new response id though, so that we can save the updated thread state under that id.
+    // We should also use the same id to save any buffered messages in the message store if there are any.
+    var newResponseId = this.GenerateResponseId();
+    if (messageStore.HasBufferedMessages)
+    {
+        await messageStore.SaveBufferedMessagesAsync(newResponseId);
+    }
+    
+    // Save the updated thread state under the new response id that was generated by the store.
+    await this._threadStore.SaveThreadAsync(newResponseId, thread);
+    return (response.Text, newResponseId);
+}
+```
+
+### Sample Scenario 2 - Structured output
+
+Currently our base abstraction does not support structured output, since the capability is not supported by all agents.
+For those agents that don't support structured output, we could add an agent decorator that takes the response from the underlying agent, and applies structured output parsing on top of it via an additional LLM call.
+
+If we add structured output configuration as a feature, then any agent that supports structured output could retrieve the configuration from the feature collection and apply it, and where it is not supported, the configuration would simply be ignored.
+
+We could add a simple StructuredOutputAgentFeature that can be added to the list of features and also be used to return the generated structured output.
+
+```csharp
+internal class StructuredOutputAgentFeature
+{
+    public Type? OutputType { get; set; }
+
+    public JsonSerializerOptions? SerializerOptions { get; set; }
+
+    public bool? UseJsonSchemaResponseFormat { get; set; }
+
+    // Contains the result of the structured output parsing request.
+    public ChatResponse? ChatResponse { get; set; }
+}
+```
+
+We can add a simple decorator class that does the chat client invocation.
+
+```csharp
+public class StructuredOutputAgent : DelegatingAIAgent
+{
+    private readonly IChatClient _chatClient;
+    public StructuredOutputAgent(AIAgent innerAgent, IChatClient chatClient)
+        : base(innerAgent)
+    {
+        this._chatClient = Throw.IfNull(chatClient);
+    }
+
+    public override async Task<AgentRunResponse> RunAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentThread? thread = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        // Run the inner agent first, to get back the text response we want to convert.
+        var response = await base.RunAsync(messages, thread, options, cancellationToken).ConfigureAwait(false);
+
+        if (options?.Features?.TryGet<StructuredOutputAgentFeature>(out var responseFormatFeature) is true
+            && responseFormatFeature.OutputType is not null)
+        {
+            // Create the chat options to request structured output.
+            ChatOptions chatOptions = new()
+            {
+                ResponseFormat = ChatResponseFormat.ForJsonSchema(responseFormatFeature.OutputType, responseFormatFeature.SerializerOptions)
+            };
+
+            // Invoke the chat client to transform the text output into structured data.
+            // The feature is updated with the result.
+            // The code can be simplified by adding a non-generic structured output GetResponseAsync
+            // overload that takes Type as input.
+            responseFormatFeature.ChatResponse = await this._chatClient.GetResponseAsync(
+                messages: new[]
+                {
+                    new ChatMessage(ChatRole.System, "You are a json expert and when provided with any text, will convert it to the requested json format."),
+                    new ChatMessage(ChatRole.User, response.Text)
+                },
+                options: chatOptions,
+                cancellationToken: cancellationToken).ConfigureAwait(false);
+        }
+
+        return response;
+    }
+}
+```
+
+Finally, we can add an extension method on `AIAgent` that can add the feature to the run options and check the feature for the structured output result and add the deserialized result to the response.
+
+```csharp
+public static async Task<AgentRunResponse<T>> RunAsync<T>(
+    this AIAgent agent,
+    IEnumerable<ChatMessage> messages,
+    AgentThread? thread = null,
+    JsonSerializerOptions? serializerOptions = null,
+    AgentRunOptions? options = null,
+    bool? useJsonSchemaResponseFormat = null,
+    CancellationToken cancellationToken = default)
+{
+    // Create the structured output feature.
+    var structuredOutputFeature = new StructuredOutputAgentFeature();
+    structuredOutputFeature.OutputType = typeof(T);
+    structuredOutputFeature.UseJsonSchemaResponseFormat = useJsonSchemaResponseFormat;
+
+    // Run the agent.
+    options ??= new AgentRunOptions();
+    options.Features ??= new AgentFeatureCollection();
+    options.Features.Set(structuredOutputFeature);
+
+    var response = await agent.RunAsync(messages, thread, options, cancellationToken).ConfigureAwait(false);
+
+    // Deserialize the JSON output.
+    if (structuredOutputFeature.ChatResponse is not null)
+    {
+        var typed = new ChatResponse<T>(structuredOutputFeature.ChatResponse, serializerOptions ?? AgentJsonUtilities.DefaultOptions);
+        return new AgentRunResponse<T>(response, typed.Result);
+    }
+
+    throw new InvalidOperationException("No structured output response was generated by the agent.");
+}
+```
+
+We can then use the extension method with any agent that supports structured output or that has
+been decorated with the `StructuredOutputAgent` decorator.
+
+```csharp
+agent = new StructuredOutputAgent(agent, chatClient);
+
+AgentRunResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>([new ChatMessage(
+    ChatRole.User,
+    "Please provide information about John Smith, who is a 35-year-old software engineer.")]);
+```
+
+## Implementation Options
+
+Three options were considered for implementing feature collections:
+
+- **Option 1**: FeatureCollections similar to ASP.NET Core
+- **Option 2**: AdditionalProperties Dictionary
+- **Option 3**: IServiceProvider
+
+Here are some comparisons about their suitability for our use case:
+
+| Criteria         | Feature Collection | Additional Properties | IServiceProvider |
+|------------------|--------------------|-----------------------|------------------|
+|Ease of use       |✅ Good             |❌ Bad                |✅ Good           |
+|User familiarity  |❌ Bad              |✅ Good               |✅ Good           |
+|Type safety       |✅ Good             |❌ Bad                |✅ Good           |
+|Ability to modify registered options when progressing down the stack|✅ Supported|✅ Supported|❌ Not-Supported (IServiceProvider is read-only)|
+|Already available in MEAI stack|❌ No|✅ Yes|❌ No|
+|Ambiguity with existing AdditionalProperties|❌ Yes|✅ No|❌ Yes|
+
+## IServiceProvider
+
+Service Collections and Service Providers provide a very popular way to register and retrieve services by type and could be used as a way to pass features to agents and chat clients.
+
+However, since IServiceProvider is read-only, it is not possible to modify the registered services when progressing down the execution stack.
+E.g. an agent decorator cannot add additional services to the IServiceProvider passed to it when calling into the inner agent.
+
+IServiceProvider also does not expose a way to list all services contained in it, making it difficult to copy services from one provider to another.
+
+This lack of mutability makes IServiceProvider unsuitable for our use case, since we will not be able to use it to build sample scenario 2.
+
+## AdditionalProperties dictionary
+
+The AdditionalProperties dictionary is already available on various options classes in the agent framework as well as in the MEAI stack and
+allows storing arbitrary key/value pairs, where the key is a string and the value is an object.
+
+While FeatureCollection uses Type as a key, AdditionalProperties uses string keys.
+This means that users need to agree on string keys to use for specific features, however it is also possible to use Type.FullName as a key by convention
+to avoid key collisions, which is an easy convention to follow.
+
+Since the value of AdditionalProperties is of type object, users need to cast the value to the expected type when retrieving it, which is also
+a drawback, but when using the convention of using Type.FullName as a key, there is at least a clear expectation of what type to cast to.
+
+```csharp
+// Setting a feature
+options.AdditionalProperties[typeof(MyFeature).FullName] = new MyFeature();
+
+// Retrieving a feature
+if (options.AdditionalProperties.TryGetValue(typeof(MyFeature).FullName, out var featureObj)
+    && featureObj is MyFeature myFeature)
+{
+    // Use myFeature
+}
+```
+
+It would also be possible to add extension methods to simplify setting and getting features from AdditionalProperties.
+Having a base class for features should help make this more feature rich.
+
+```csharp
+// Setting a feature, this can use Type.FullName as the key.
+options.AdditionalProperties
+    .WithFeature(new MyFeature());
+
+// Retrieving a feature, this can use Type.FullName as the key.
+if (options.AdditionalProperties.TryGetFeature<MyFeature>(out var myFeature))
+{
+    // Use myFeature
+}
+```
+
+It would also be possible to add extension methods for a feature to simplify setting and getting features from AdditionalProperties.
+
+```csharp
+// Setting a feature
+options.AdditionalProperties
+    .WithMyFeature(new MyFeature());
+// Retrieving a feature
+if (options.AdditionalProperties.TryGetMyFeature(out var myFeature))
+{
+    // Use myFeature
+}
+```
+
+## Feature Collection
+
+If we choose the feature collection option, we need to decide on the design of the feature collection itself.
+
+### Feature Collections extension points
+
+We need to decide the set of actions that feature collections would be supported for. Here is the suggested list of actions:
+
+**MAAI.AIAgent:**
+
+1. GetNewThread
+    1. E.g. this would allow passing an already existing storage id for the thread to use, or an initialized custom chat message store to use.
+1. DeserializeThread
+    1. E.g. this would allow passing an already existing storage id for the thread to use, or an initialized custom chat message store to use.
+1. Run / RunStreaming
+    1. E.g. this would allow passing an override chat message store just for that run, or a desired schema for a structured output middleware component.
+
+**MEAI.ChatClient:**
+
+1. GetResponse / GetStreamingResponse
+
+### Reconciling with existing AdditionalProperties
+
+If we decide to add feature collections, separately from the existing AdditionalProperties dictionaries, we need to consider how to explain to users when to use each one.
+One possible approach though is to have the one use the other under the hood.
+AdditionalProperties could be stored as a feature in the feature collection.
+
+Users would be able to retrieve additional properties from the feature collection, in addition to retrieving it via a dedicated AdditionalProperties property.
+E.g. `features.Get<AdditionalPropertiesDictionary>()`
+
+One challenge with this approach is that when setting a value in the AdditionalProperties dictionary, the feature collection would need to be created first if it does not already exist.
+
+```csharp
+public class AgentRunOptions
+{
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+    public IAgentFeatureCollection? Features { get; set; }
+}
+
+var options = new AgentRunOptions();
+// This would need to create the feature collection first, if it does not already exist.
+options.AdditionalProperties ??= new AdditionalPropertiesDictionary();
+```
+
+Since IAgentFeatureCollection is an interface, AgentRunOptions would need to have a concrete implementation of the interface to create, meaning that the user cannot decide.
+It also means that if the user doesn't realise that AdditionalProperties is implemented using feature collections, they may set a value on AdditionalProperties, and then later overwrite the entire feature collection, losing the AdditionalProperties feature.
+
+Options to avoid these issues:
+
+1. Make `Features` readonly.
+    1. This would prevent the user from overwriting the feature collection after setting AdditionalProperties.
+    1. Since the user cannot set their own implementation of IAgentFeatureCollection, having an interface for it may not be necessary.
+
+### Feature Collection Implementation
+
+We have two options for implementing feature collections:
+
+1. Create our own [IAgentFeatureCollection interface](https://github.com/microsoft/agent-framework/pull/2354/files#diff-9c42f3e60d70a791af9841d9214e038c6de3eebfc10e3997cb4cdffeb2f1246d) and [implementation](https://github.com/microsoft/agent-framework/pull/2354/files#diff-a435cc738baec500b8799f7f58c1538e3bb06c772a208afc2615ff90ada3f4ca).
+2. Reuse the asp.net [IFeatureCollection interface](https://github.com/dotnet/aspnetcore/blob/main/src/Extensions/Features/src/IFeatureCollection.cs) and [implementation](https://github.com/dotnet/aspnetcore/blob/main/src/Extensions/Features/src/FeatureCollection.cs).
+
+#### Roll our own
+
+Advantages:
+
+Creating our own IAgentFeatureCollection interface and implementation has the advantage of being more clearly associated with the agent framework and allows us to
+improve on some of the design decisions made in asp.net core's IFeatureCollection.
+
+Drawbacks:
+
+It would mean a different implementation to maintain and test.
+
+#### Reuse asp.net IFeatureCollection
+
+Advantages:
+
+Reusing the asp.net IFeatureCollection has the advantage of being able to reuse the well-established and tested implementation from asp.net
+core. Users who are using agents in an asp.net core application may be able to pass feature collections from asp.net core to the agent framework directly.
+
+Drawbacks:
+
+While the package name is `Microsoft.Extensions.Features`, the namespaces of the types are `Microsoft.AspNetCore.Http.Features`, which may create confusion for users of agent framework who are not building web applications or services.
+Users may rightly ask: Why do I need to use a class from asp.net core when I'm not building a web application / service?
+
+The current design has some design issues that would be good to avoid.  E.g. it does not distinguish between a feature being "not set" and "null". Get returns both as null and there is no tryget method.
+Since the [default implementation](https://github.com/dotnet/aspnetcore/blob/main/src/Extensions/Features/src/FeatureCollection.cs) also supports value types, it throws for null values of value types.
+A TryGet method would be more appropriate.
+
+## Feature Layering
+
+One possible scenario when adding support for feature collections is to allow layering of features by scope.
+
+The following levels of scope could be supported:
+
+1. Application - Application wide features that apply to all agents / chat clients
+2. Artifact (Agent / ChatClient) - Features that apply to all runs of a specific agent or chat client instance
+3. Action (GetNewThread / Run / GetResponse) - Feature that apply to a single action only
+
+When retrieving a feature from the collection, the search would start from the most specific scope (Action) and progress to the least specific scope (Application), returning the first matching feature found.
+
+Introducing layering adds some challenges:
+
+- There may be multiple feature collections at the same scope level, e.g. an Agent that uses a ChatClient where both have their own feature collections.
+  - Do we layer the agent feature collection over the chat client feature collection (Application -> ChatClient -> Agent -> Run), or only use the agent feature collection in the agent (Application -> Agent -> Run), and the chat client feature collection in the chat client (Application -> ChatClient -> Run)?
+- The appropriate base feature collection may change when progressing down the stack, e.g. when an Agent calls a ChatClient, the action feature collection stays the same, but the artifact feature collection changes.
+- Who creates the feature collection hierarchy?
+  - Since the hierarchy changes as it progresses down the execution stack, and the caller can only pass in the action level feature collection, the callee needs to combine it with its own artifact level feature collection and the application level feature collection. Each action will need to build the appropriate feature collection hierarchy, at the start of its execution.
+- For Artifact level features, it seems odd to pass them in as a bag of untyped features, when we are constructing a known artifact type and therefore can have typed settings.
+  - E.g. today we have a strongly typed setting on ChatClientAgentOptions to configure a ChatMessageStore for the agent.
+- To avoid global statics for application level features, the user would need to pass in the application level feature collection to each artifact that they create.
+  - This would be very odd if the user also already has to strongly typed settings for each feature that they want to set at the artifact level.
+
+### Layering Options
+
+1. No layering - only a single feature collection is supported per action (the caller can still create a layered collection if desired, but the callee does not do any layering automatically).
+    1. Fallback is to any features configured on the artifact via strongly typed settings.
+1. Full layering - support layering at all levels (Application -> Artifact -> Action).
+    1. Only apply applicable artifact level features when calling into that artifact.
+    1. Apply upstream artifact features when calling into downstream artifacts, e.g. Feature hierarchy in ChatClientAgent would be `Application -> Agent -> Run` and in ChatClient would be `Application -> ChatClient -> Agent -> Run` or `Application -> Agent -> ChatClient -> Run`
+    1. The user needs to provide the application level feature collection to each artifact that they create and artifact features are passed via strongly typed settings.
+
+### Accessing application level features Options
+
+We need to consider how application level features would be accessed if supported.
+
+1. The user provides the application level feature collection to each artifact that the user constructs
+    1. Passing the application level feature collection to each artifact is tedious for the user.
+1. There is a static application level feature collection that can be accessed globally.
+    1. Statics create issues with testing and isolation.
+
+## Decisions
+
+- Feature Collections Container: Use AdditionalProperties
+- Feature Layering: No layering - only a single collection/dictionary is supported per action. Application layers can be added later if needed.

docs/decisions/0015-agent-run-context.md

@@ -0,0 +1,147 @@
+---
+status: proposed
+contact: westey-m
+date: 2026-01-27
+deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub, lokitoth, alliscode, taochenosu, moonbox3
+consulted: 
+informed: 
+---
+
+# AgentRunContext for Agent Run
+
+## Context and Problem Statement
+
+During an agent run, various components involved in the execution (middleware, filters, tools, nested agents, etc.) may need access to contextual information about the current run, such as:
+
+1. The agent that is executing the run
+2. The session associated with the run
+3. The request messages passed to the agent
+4. The run options controlling the agent's behavior
+
+Additionally, some components may need to modify this context during execution, for example:
+
+- Replacing the session with a different one
+- Modifying the request messages before they reach the agent core
+- Updating or replacing the run options entirely
+
+Currently, there is no standardized way to access or modify this context from arbitrary code that executes during an agent run, especially from deeply nested call stacks where the context is not explicitly passed.
+
+## Sample Scenario
+
+When using an Agent as an AIFunction developers may want to pass context from the parent agent run to the child agent run. For example, the developer may want to copy chat history to the child agent, or share the same session across both agents.
+
+To enable these scenarios, we need a way to access the parent agent run context, including e.g. the parent agent itself, the parent agent session, and the parent run options from function tool calls.
+
+```csharp
+    public static AIFunction AsAIFunctionWithSessionPropagation(this ChatClientAgent agent, AIFunctionFactoryOptions? options = null)
+    {
+        Throw.IfNull(agent);
+
+        [Description("Invoke an agent to retrieve some information.")]
+        async Task<string> InvokeAgentAsync(
+            [Description("Input query to invoke the agent.")] string query,
+            CancellationToken cancellationToken)
+        {
+            // Get the session from the parent agent and pass it to the child agent.
+            var session = AIAgent.CurrentRunContext?.Session;
+
+            // Alternatively, the developer may want to create a new session but copy over the chat history from the parent agent.
+            // var parentChatHistory = AIAgent.CurrentRunContext?.Session?.GetService<IList<ChatMessage>>();
+            // if (parentChatHistory != null)
+            // {
+            //     var chp = new InMemoryChatHistoryProvider();
+            //     foreach (var message in parentChatHistory)
+            //     {
+            //         chp.Add(message);
+            //     }
+            //     session = agent.GetNewSession(chp);
+            // }
+
+            var response = await agent.RunAsync(query, session: session, cancellationToken: cancellationToken).ConfigureAwait(false);
+            return response.Text;
+        }
+
+        options ??= new();
+        options.Name ??= SanitizeAgentName(agent.Name);
+        options.Description ??= agent.Description;
+
+        return AIFunctionFactory.Create(InvokeAgentAsync, options);
+    }
+```
+
+## Decision Drivers
+
+- Components executing during an agent run need access to run context without explicit parameter passing through every layer
+- Context should flow naturally across async calls without manual propagation
+- The design should allow modification of context properties by agent decorators (e.g., replacing options or session)
+- Solution should be consistent with patterns used in similar frameworks (e.g., `FunctionInvokingChatClient.CurrentContext` `HttpContext.Current`, `Activity.Current`)
+
+## Considered Options
+
+- **Option 1**: Pass context explicitly through all method signatures
+- **Option 2**: Use `AsyncLocal<T>` to provide ambient context accessible anywhere during the run
+- **Option 3**: Use a combination of explicit parameters for `RunCoreAsync` and `AsyncLocal<T>` for ambient access
+
+## Decision Outcome
+
+Chosen option: **Option 3** - Combination of explicit parameters and AsyncLocal ambient access.
+
+This approach provides the best of both worlds:
+
+1. **Explicit parameters are passed to `RunCoreAsync`**: The core agent implementation receives the parameters explicitly, making it clear what data is available and enabling easy unit testing. Any modification of these in a decorator will require calling `RunAsync` on the inner agent with the updated parameters, which would result in the inner agent creating a new `AgentRunContext` instance.
+
+   ```csharp
+    public async Task<AgentResponse> RunAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+
+        CurrentRunContext = new(this, session, messages as IReadOnlyCollection<ChatMessage> ?? messages.ToList(), options);
+        return await this.RunCoreAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
+    }
+   ```
+
+2. **`AsyncLocal<AgentRunContext?>` for ambient access**: The context is stored in an `AsyncLocal<T>` field, making it accessible from any code executing during the agent run via a static property.
+
+    The main scenario for this is to allow deeply nested components (e.g., tools, chat client middleware) to access the context without needing to pass it through every method signature. These are external components that cannot easily be modified to accept additional parameters. For internal components, we prefer passing any parameters explicitly.
+
+   ```csharp
+   public static AgentRunContext? CurrentRunContext
+   {
+       get => s_currentContext.Value;
+       protected set => s_currentContext.Value = value;
+   }
+   ```
+
+### AgentRunContext Design
+
+The `AgentRunContext` class encapsulates all run-related state:
+
+```csharp
+public class AgentRunContext
+{
+    public AgentRunContext(
+        AIAgent agent,
+        AgentSession? session,
+        IReadOnlyCollection<ChatMessage> requestMessages,
+        AgentRunOptions? agentRunOptions)
+
+    public AIAgent Agent { get; }
+    public AgentSession? Session { get; }
+    public IReadOnlyCollection<ChatMessage> RequestMessages { get; }
+    public AgentRunOptions? RunOptions { get; }
+}
+```
+
+Key design decisions:
+
+- **All properties are read-only**: While some of the sub-properties on the provided properties (like `AgentRunOptions.AllowBackgroundResponses`) may be mutable, the `AgentRunContext` itself is immutable and we want to discourage anyone modifying the values in the context.  Modifying the context is unlikely to result in the desired behavior, as the values will typically already have been used by the time any custom code accesses them.
+
+### Benefits
+
+1. **Ambient Access**: Any code executing during the run can access context via `AIAgent.CurrentRunContext` without needing explicit parameters
+2. **Async Flow**: `AsyncLocal<T>` automatically flows across async/await boundaries
+3. **Modifiability**: Components can modify or replace session, messages, or options as needed
+4. **Testability**: The explicit parameter to `RunCoreAsync` makes unit testing straightforward

docs/design/README.md

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

docs/design/agents.md

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

docs/design/context_providers.md

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

docs/design/evaluation.md

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

docs/design/guardrails.md

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

docs/design/mcp-servers.md

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

docs/design/models.md

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

docs/design/observability.md

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

docs/design/optimization.md

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

docs/design/python-package-setup.md

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

docs/design/threads.md

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

docs/design/tools.md

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

docs/design/types.md

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

docs/design/vector-stores.md

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

docs/design/workflows.md

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

docs/features/durable-agents/durable-agents-ttl.md

@@ -0,0 +1,147 @@
+# Time-To-Live (TTL) for durable agent sessions
+
+## Overview
+
+The durable agents automatically maintain conversation history and state for each session. Without automatic cleanup, this state can accumulate indefinitely, consuming storage resources and increasing costs. The Time-To-Live (TTL) feature provides automatic cleanup of idle agent sessions, ensuring that sessions are automatically deleted after a period of inactivity.
+
+## What is TTL?
+
+Time-To-Live (TTL) is a configurable duration that determines how long an agent session state will be retained after its last interaction. When an agent session is idle (no messages sent to it) for longer than the TTL period, the session state is automatically deleted. Each new interaction with an agent resets the TTL timer, extending the session's lifetime.
+
+## Benefits
+
+- **Automatic cleanup**: No manual intervention required to clean up idle agent sessions
+- **Cost optimization**: Reduces storage costs by automatically removing unused session state
+- **Resource management**: Prevents unbounded growth of agent session state in storage
+- **Configurable**: Set TTL globally or per-agent type to match your application's needs
+
+## Configuration
+
+TTL can be configured at two levels:
+
+1. **Global default TTL**: Applies to all agent sessions unless overridden
+2. **Per-agent type TTL**: Overrides the global default for specific agent types
+
+Additionally, you can configure a **minimum deletion delay** that controls how frequently deletion operations are scheduled. The default value is 5 minutes, and the maximum allowed value is also 5 minutes.
+
+> [!NOTE]
+> Reducing the minimum deletion delay below 5 minutes can be useful for testing or for ensuring rapid cleanup of short-lived agent sessions. However, this can also increase the load on the system and should be used with caution.
+
+### Default values
+
+- **Default TTL**: 14 days
+- **Minimum TTL deletion delay**: 5 minutes (maximum allowed value, subject to change in future releases)
+
+### Configuration examples
+
+#### .NET
+
+```csharp
+// Configure global default TTL and minimum signal delay
+services.ConfigureDurableAgents(
+    options =>
+    {
+        // Set global default TTL to 7 days
+        options.DefaultTimeToLive = TimeSpan.FromDays(7);
+
+        // Add agents (will use global default TTL)
+        options.AddAIAgent(myAgent);
+    });
+
+// Configure per-agent TTL
+services.ConfigureDurableAgents(
+    options =>
+    {
+        options.DefaultTimeToLive = TimeSpan.FromDays(14); // Global default
+        
+        // Agent with custom TTL of 1 day
+        options.AddAIAgent(shortLivedAgent, timeToLive: TimeSpan.FromDays(1));
+        
+        // Agent with custom TTL of 90 days
+        options.AddAIAgent(longLivedAgent, timeToLive: TimeSpan.FromDays(90));
+        
+        // Agent using global default (14 days)
+        options.AddAIAgent(defaultAgent);
+    });
+
+// Disable TTL for specific agents by setting TTL to null
+services.ConfigureDurableAgents(
+    options =>
+    {
+        options.DefaultTimeToLive = TimeSpan.FromDays(14);
+        
+        // Agent with no TTL (never expires)
+        options.AddAIAgent(permanentAgent, timeToLive: null);
+    });
+```
+
+## How TTL works
+
+The following sections describe how TTL works in detail.
+
+### Expiration tracking
+
+Each agent session maintains an expiration timestamp in its internally managed state that is updated whenever the session processes a message:
+
+1. When a message is sent to an agent session, the expiration time is set to `current time + TTL`
+2. The runtime schedules a delete operation for the expiration time (subject to minimum delay constraints)
+3. When the delete operation runs, if the current time is past the expiration time, the session state is deleted. Otherwise, the delete operation is rescheduled for the next expiration time.
+
+### State deletion
+
+When an agent session expires, its entire state is deleted, including:
+
+- Conversation history
+- Any custom state data
+- Expiration timestamps
+
+After deletion, if a message is sent to the same agent session, a new session is created with a fresh conversation history.
+
+## Behavior examples
+
+The following examples illustrate how TTL works in different scenarios.
+
+### Example 1: Agent session expires after TTL
+
+1. Agent configured with 30-day TTL
+2. User sends message at Day 0 → agent session created, expiration set to Day 30
+3. No further messages sent
+4. At Day 30 → Agent session is deleted
+5. User sends message at Day 31 → New agent session created with fresh conversation history
+
+### Example 2: TTL reset on interaction
+
+1. Agent configured with 30-day TTL
+2. User sends message at Day 0 → agent session created, expiration set to Day 30
+3. User sends message at Day 15 → Expiration reset to Day 45
+4. User sends message at Day 40 → Expiration reset to Day 70
+5. Agent session remains active as long as there are regular interactions
+
+## Logging
+
+The TTL feature includes comprehensive logging to track state changes:
+
+- **Expiration time updated**: Logged when TTL expiration time is set or updated
+- **Deletion scheduled**: Logged when a deletion check signal is scheduled
+- **Deletion check**: Logged when a deletion check operation runs
+- **Session expired**: Logged when an agent session is deleted due to expiration
+- **TTL rescheduled**: Logged when a deletion signal is rescheduled
+
+These logs help monitor TTL behavior and troubleshoot any issues.
+
+## Best practices
+
+1. **Choose appropriate TTL values**: Balance between storage costs and user experience. Too short TTLs may delete active sessions, while too long TTLs may accumulate unnecessary state.
+
+2. **Use per-agent TTLs**: Different agents may have different usage patterns. Configure TTLs per-agent based on expected session lifetimes.
+
+3. **Monitor expiration logs**: Review logs to understand TTL behavior and adjust configuration as needed.
+
+4. **Test with short TTLs**: During development, use short TTLs (e.g., minutes) to verify TTL behavior without waiting for long periods.
+
+## Limitations
+
+- TTL is based on wall-clock time, not activity time. The expiration timer starts from the last message timestamp.
+- Deletion checks are durably scheduled operations and may have slight delays depending on system load.
+- Once an agent session is deleted, its conversation history cannot be recovered.
+- TTL deletion requires at least one worker to be available to process the deletion operation message.

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 `AgentResponse` 
+- [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 `AgentResponse` 
+- [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 `AgentResponse` 
+- [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 `AgentResponse` 
+- [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");
+AgentResponse 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,41 @@ 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.CA2252.severity = none # Requires preview
 dotnet_diagnostic.CA2253.severity = none # Named placeholders in the logging message template should not be comprised of only numeric characters
 dotnet_diagnostic.CA2253.severity = none # Named placeholders in the logging message template should not be comprised of only numeric characters
 dotnet_diagnostic.CA2263.severity = suggestion # Use generic overload
-dotnet_diagnostic.CS1998.severity = suggestion # async method lacks 'await' operators and will run synchronously
+dotnet_diagnostic.CA5394.severity = none # Do not use insecure sources of randomness
 
 dotnet_diagnostic.VSTHRD003.severity = none # Waiting on thread from another context
 dotnet_diagnostic.VSTHRD103.severity = none # Use async equivalent; analyzer is currently noisy
 dotnet_diagnostic.VSTHRD111.severity = none # Use .ConfigureAwait(bool) is hidden by default, set to none to prevent IDE from changing on autosave
-dotnet_diagnostic.VSTHRD200.severity = none # Use Async suffix for async methods
-dotnet_diagnostic.xUnit1004.severity = none # Test methods should not be skipped. Remove the Skip property to start running the test again.
 
-dotnet_diagnostic.RCS1021.severity = none # Use expression-bodied lambda.
+dotnet_diagnostic.xUnit1004.severity = none # Test methods should not be skipped. Remove the Skip property to start running the test again.
+dotnet_diagnostic.xUnit1042.severity = none # Untyped data rows
+
 dotnet_diagnostic.RCS1032.severity = none # Remove redundant parentheses.
-dotnet_diagnostic.RCS1061.severity = none # Merge 'if' with nested 'if'.
-dotnet_diagnostic.RCS1069.severity = none # Remove unnecessary case label.
 dotnet_diagnostic.RCS1074.severity = none # Remove redundant constructor.
-dotnet_diagnostic.RCS1077.severity = none # Optimize LINQ method call.
-dotnet_diagnostic.RCS1118.severity = none # Mark local variable as const.
-dotnet_diagnostic.RCS1124.severity = none # Inline local variable.
-dotnet_diagnostic.RCS1129.severity = none # Remove redundant field initialization.
 dotnet_diagnostic.RCS1140.severity = none # Add exception to documentation comment.
 dotnet_diagnostic.RCS1141.severity = none # Add 'param' element to documentation comment.
 dotnet_diagnostic.RCS1142.severity = none # Add 'typeparam' element to documentation comment.
-dotnet_diagnostic.RCS1146.severity = none # Use conditional access.
 dotnet_diagnostic.RCS1151.severity = none # Remove redundant cast.
 dotnet_diagnostic.RCS1158.severity = none # Static member in generic type should use a type parameter.
 dotnet_diagnostic.RCS1161.severity = none # Enum should declare explicit value
 dotnet_diagnostic.RCS1163.severity = none # Unused parameter 'foo'.
-dotnet_diagnostic.RCS1170.severity = none # Use read-only auto-implemented property.
-dotnet_diagnostic.RCS1173.severity = none # Use coalesce expression instead of 'if'.
 dotnet_diagnostic.RCS1181.severity = none # Convert comment to documentation comment.
-dotnet_diagnostic.RCS1186.severity = none # Use Regex instance instead of static method.
-dotnet_diagnostic.RCS1188.severity = none # Remove redundant auto-property initialization.
 dotnet_diagnostic.RCS1189.severity = none # Add region name to #endregion.
-dotnet_diagnostic.RCS1197.severity = none # Optimize StringBuilder.AppendLine call.
-dotnet_diagnostic.RCS1201.severity = none # Use method chaining.
 dotnet_diagnostic.RCS1205.severity = none # Order named arguments according to the order of parameters.
 dotnet_diagnostic.RCS1212.severity = none # Remove redundant assignment.
 dotnet_diagnostic.RCS1217.severity = none # Convert interpolated string to concatenation.
@@ -218,38 +241,28 @@ dotnet_diagnostic.RCS1226.severity = none # Add paragraph to documentation comme
 dotnet_diagnostic.RCS1229.severity = none # Use async/await when necessary.
 dotnet_diagnostic.RCS1234.severity = none # Enum duplicate value
 dotnet_diagnostic.RCS1238.severity = none # Avoid nested ?: operators.
-dotnet_diagnostic.RCS1241.severity = none # Implement IComparable when implementing IComparable<T><T>.
+dotnet_diagnostic.RCS1241.severity = none # Implement IComparable when implementing IComparable<T>
+dotnet_diagnostic.RCS1246.severity = none # Use element access
+dotnet_diagnostic.RCS1261.severity = none # Resource can be disposed asynchronously
 
-dotnet_diagnostic.IDE0001.severity = none # Simplify name
-dotnet_diagnostic.IDE0002.severity = none # Simplify member access
-dotnet_diagnostic.IDE0004.severity = none # Remove unnecessary cast
 dotnet_diagnostic.IDE0010.severity = none # Populate switch
 dotnet_diagnostic.IDE0021.severity = none # Use block body for constructors
 dotnet_diagnostic.IDE0022.severity = none # Use block body for methods
 dotnet_diagnostic.IDE0024.severity = none # Use block body for operator
-dotnet_diagnostic.IDE0035.severity = none # Remove unreachable code
-dotnet_diagnostic.IDE0051.severity = none # Remove unused private member
-dotnet_diagnostic.IDE0052.severity = none # Remove unread private member
-dotnet_diagnostic.IDE0058.severity = none # Remove unused expression value
-dotnet_diagnostic.IDE0059.severity = none # Unnecessary assignment of a value
+dotnet_diagnostic.IDE0042.severity = none # Variable declaration can be deconstructed
+dotnet_diagnostic.IDE0046.severity = none # if statement can be simplified
+dotnet_diagnostic.IDE0056.severity = none # Indexing can be simplified
+dotnet_diagnostic.IDE0057.severity = none # Substring can be simplified
 dotnet_diagnostic.IDE0060.severity = none # Remove unused parameter
 dotnet_diagnostic.IDE0061.severity = none # Use block body for local function
 dotnet_diagnostic.IDE0079.severity = none # Remove unnecessary suppression.
 dotnet_diagnostic.IDE0080.severity = none # Remove unnecessary suppression operator.
 dotnet_diagnostic.IDE0100.severity = none # Remove unnecessary equality operator
-dotnet_diagnostic.IDE0110.severity = none # Remove unnecessary discards
 dotnet_diagnostic.IDE0130.severity = none # Namespace does not match folder structure
-dotnet_diagnostic.IDE0290.severity = none # Use primary constructor
-dotnet_diagnostic.IDE0032.severity = none # Use auto property
 dotnet_diagnostic.IDE0160.severity = none # Use block-scoped namespace
-dotnet_diagnostic.IDE1006.severity = warning # Naming rule violations
-dotnet_diagnostic.IDE0046.severity = suggestion # If statement can be simplified
-dotnet_diagnostic.IDE0056.severity = suggestion # Indexing can be simplified
-dotnet_diagnostic.IDE0057.severity = suggestion # Substring can be simplified
-
-dotnet_diagnostic.CA2007.severity = error # Do not directly await a Task
-dotnet_diagnostic.VSTHRD111.severity = error # Use .ConfigureAwait(bool)
-dotnet_diagnostic.IDE1006.severity = error # Naming rule violations
+dotnet_diagnostic.IDE0290.severity = none # Use primary constructor
+dotnet_diagnostic.IDE0305.severity = none # ToList can be simplified
+dotnet_diagnostic.IDE0330.severity = none # Use 'System.Threading.Lock'
 
 # Testing
 dotnet_diagnostic.Moq1400.severity = none # Explicitly choose a mocking behavior instead of relying on the default (Loose) behavior
@@ -430,3 +443,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/AGENTS.md

@@ -0,0 +1,66 @@
+# AGENTS.md
+
+Instructions for AI coding agents working in the .NET codebase.
+
+## Build, Test, and Lint Commands
+
+```bash
+# From dotnet/ directory
+dotnet build              # Build all projects
+dotnet test               # Run all tests
+dotnet format             # Auto-fix formatting
+
+# Build/test a specific project (preferred for isolated changes)
+dotnet build src/Microsoft.Agents.AI.<Package>
+dotnet test tests/Microsoft.Agents.AI.<Package>.UnitTests
+
+# Run a single test
+dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName"
+```
+
+**Note**: Changes to core packages (`Microsoft.Agents.AI`, `Microsoft.Agents.AI.Abstractions`) affect dependent projects - run checks across the entire solution. For isolated changes, build/test only the affected project to save time.
+
+## Project Structure
+
+```
+dotnet/
+├── src/
+│   ├── Microsoft.Agents.AI/              # Core AI agent abstractions
+│   ├── Microsoft.Agents.AI.Abstractions/ # Shared abstractions and interfaces
+│   ├── Microsoft.Agents.AI.OpenAI/       # OpenAI provider
+│   ├── Microsoft.Agents.AI.AzureAI/      # Azure AI provider
+│   ├── Microsoft.Agents.AI.Anthropic/    # Anthropic provider
+│   ├── Microsoft.Agents.AI.Workflows/    # Workflow orchestration
+│   └── ...                               # Other packages
+├── samples/                              # Sample applications
+└── tests/                                # Unit and integration tests
+```
+
+### External Dependencies
+
+The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extensions.AI.Abstractions` (external NuGet packages) using types like `IChatClient`, `FunctionInvokingChatClient`, `AITool`, and `AIContent`.
+
+## Key Conventions
+
+- **Copyright header**: `// Copyright (c) Microsoft. All rights reserved.` at top of all `.cs` files
+- **XML docs**: Required for all public methods and classes
+- **Async**: Use `Async` suffix for methods returning `Task`/`ValueTask`
+- **Private classes**: Should be `sealed` unless subclassed
+- **Config**: Read from environment variables with `UPPER_SNAKE_CASE` naming
+- **Tests**: Add Arrange/Act/Assert comments; use Moq for mocking
+
+## Sample Structure
+
+1. Copyright header: `// Copyright (c) Microsoft. All rights reserved.`
+2. Description comment explaining what the sample demonstrates
+3. Using statements
+4. Main code logic
+5. Helper methods at bottom
+
+Configuration via environment variables (never hardcode secrets). Keep samples simple and focused.
+
+When adding a new sample:
+- Create a standalone project in `samples/` with matching directory and project names
+- Include a README.md explaining what the sample does and how to run it
+- Add the project to the solution file
+- Reference the sample in the parent directory's README.md

dotnet/Directory.Build.props

@@ -3,17 +3,16 @@
     <!-- Default properties inherited by all projects. Projects can override. -->
     <RunAnalyzersDuringBuild>true</RunAnalyzersDuringBuild>
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
-    <AnalysisMode>AllEnabledByDefault</AnalysisMode>
-    <AnalysisLevel>latest</AnalysisLevel>
+    <AnalysisLevel>10.0-all</AnalysisLevel>
     <GenerateDocumentationFile>true</GenerateDocumentationFile>
-    <LangVersion>12</LangVersion>
+    <LangVersion>latest</LangVersion>
     <Nullable>enable</Nullable>
-    <ImplicitUsings>disable</ImplicitUsings>
-    <NoWarn>$(NoWarn);IDE0290;IDE0079;NU5128</NoWarn>
+    <NoWarn>$(NoWarn);NU5128;CS8002</NoWarn>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
-    <ProjectsTargetFrameworks>net9.0;net8.0;netstandard2.0;net472</ProjectsTargetFrameworks>
-    <ProjectsDebugTargetFrameworks>net9.0;net472</ProjectsDebugTargetFrameworks>
+    <TargetFrameworksCore>net10.0;net9.0;net8.0</TargetFrameworksCore>
+    <TargetFrameworks>$(TargetFrameworksCore);netstandard2.0;net472</TargetFrameworks>
     <IsAotCompatible Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net7.0'))">true</IsAotCompatible>
+    <Configurations>Debug;Release;Publish</Configurations>
   </PropertyGroup>
 
   <PropertyGroup>
@@ -22,7 +21,7 @@
   
   <PropertyGroup>
     <!-- Disable NuGet packaging by default. Projects can override. -->
-    <IsPackable>disable</IsPackable>
+    <IsPackable>false</IsPackable>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(Configuration)'=='Publish'">
@@ -31,7 +30,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.Build.targets

@@ -5,7 +5,7 @@
   <Sdk Name="Microsoft.Build.CentralPackageVersions" Version="2.1.3" />
   <!-- Only run 'dotnet format' on dev machines, Release builds. Skip on GitHub Actions -->
   <!-- as this runs in its own Actions job. -->
-  <Target Name="DotnetFormatOnBuild" BeforeTargets="Build" Condition=" '$(Configuration)' == 'Release' AND '$(GITHUB_ACTIONS)' == '' AND '$(TargetFramework)' == '$(ProjectsDebugTargetFrameworks)'">
+  <Target Name="DotnetFormatOnBuild" BeforeTargets="Build" Condition=" '$(Configuration)' == 'Release' AND '$(GITHUB_ACTIONS)' == '' ">
     <Message Text="Running dotnet format" Importance="high" />
     <Exec Command="dotnet format --no-restore -v diag $(ProjectFileName)" />
   </Target>