minor tweaks

.devcontainer/dotnet/devcontainer.json

@@ -1,30 +1,16 @@
 {
   "name": "C# (.NET)",
-  "image": "mcr.microsoft.com/devcontainers/dotnet",
+  "image": "mcr.microsoft.com/devcontainers/dotnet:10.0",
   "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": {}
+    "ghcr.io/devcontainers/features/dotnet:2.4.0": {},
+    "ghcr.io/devcontainers/features/powershell:1.5.1": {},
+    "ghcr.io/devcontainers/features/azure-cli:1.2.8": {},
+    "ghcr.io/devcontainers/features/docker-in-docker:2.12.4": {}
   },
   "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"

.github/CODEOWNERS

@@ -2,6 +2,3 @@
 # 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/actions/azure-functions-integration-setup/action.yml

@@ -12,7 +12,7 @@ runs:
             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
+          docker run -d --name dts-emulator -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest
           echo "Waiting for Durable Task Scheduler Emulator to be ready"
           timeout 30 bash -c 'until curl --silent http://localhost:8080/healthz; do sleep 1; done'
           echo "Durable Task Scheduler Emulator is ready"

.github/actions/sample-validation-setup/action.yml

@@ -1,48 +0,0 @@
-name: Sample Validation Setup
-description: Sets up the environment for sample validation (checkout, Node.js, Copilot CLI, Azure login, Python)
-
-inputs:
-  azure-client-id:
-    description: Azure Client ID for OIDC login
-    required: true
-  azure-tenant-id:
-    description: Azure Tenant ID for OIDC login
-    required: true
-  azure-subscription-id:
-    description: Azure Subscription ID for OIDC login
-    required: true
-  python-version:
-    description: The Python version to set up
-    required: false
-    default: "3.12"
-  os:
-    description: The operating system to set up
-    required: false
-    default: "Linux"
-
-runs:
-  using: "composite"
-  steps:
-    - name: Set up Node.js environment
-      uses: actions/setup-node@v4
-
-    - name: Install Copilot CLI
-      shell: bash
-      run: npm install -g @github/copilot
-
-    - name: Test Copilot CLI
-      shell: bash
-      run: copilot -p "What can you do in one sentence?"
-
-    - name: Azure CLI Login
-      uses: azure/login@v2
-      with:
-        client-id: ${{ inputs.azure-client-id }}
-        tenant-id: ${{ inputs.azure-tenant-id }}
-        subscription-id: ${{ inputs.azure-subscription-id }}
-
-    - name: Set up python and install the project
-      uses: ./.github/actions/python-setup
-      with:
-        python-version: ${{ inputs.python-version }}
-        os: ${{ inputs.os }}

.github/copilot-instructions.md

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

.github/labeler.yml

@@ -23,7 +23,7 @@ workflows:
   - any-glob-to-any-file:
     - dotnet/src/Microsoft.Agents.AI.Workflows/**
     - dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/**
-    - dotnet/samples/03-workflows/**
+    - dotnet/samples/GettingStarted/Workflow/**
     - python/packages/main/agent_framework/_workflow/**
     - python/samples/getting_started/workflow/**
 

.github/upgrades/prompts/SemanticKernelToAgentFramework.md

@@ -105,7 +105,7 @@ After completing migration, verify these specific items:
 1. **Compilation**: Execute `dotnet build` on all modified projects - zero errors required
 2. **Namespace Updates**: Confirm all `using Microsoft.SemanticKernel.Agents` statements are replaced
 3. **Method Calls**: Verify all `InvokeAsync` calls are changed to `RunAsync`
-4. **Return Types**: Confirm handling of `AgentResponse` instead of `IAsyncEnumerable<AgentResponseItem<ChatMessageContent>>`
+4. **Return Types**: Confirm handling of `AgentRunResponse` instead of `IAsyncEnumerable<AgentResponseItem<ChatMessageContent>>`
 5. **Thread Creation**: Validate all thread creation uses `agent.GetNewThread()` pattern
 6. **Tool Registration**: Ensure `[KernelFunction]` attributes are removed and `AIFunctionFactory.Create()` is used
 7. **Options Configuration**: Verify `AgentRunOptions` or `ChatClientAgentRunOptions` replaces `AgentInvokeOptions`
@@ -119,7 +119,7 @@ Agent Framework provides functionality for creating and managing AI agents throu
 Key API differences:
 - Agent creation: Remove Kernel dependency, use direct client-based creation
 - Method names: `InvokeAsync` → `RunAsync`, `InvokeStreamingAsync` → `RunStreamingAsync`
-- Return types: `IAsyncEnumerable<AgentResponseItem<ChatMessageContent>>` → `AgentResponse`
+- Return types: `IAsyncEnumerable<AgentResponseItem<ChatMessageContent>>` → `AgentRunResponse`
 - Thread creation: Provider-specific constructors → `agent.GetNewThread()`
 - Tool registration: `KernelPlugin` system → Direct `AIFunction` registration
 - Options: `AgentInvokeOptions` → Provider-specific run options (e.g., `ChatClientAgentRunOptions`)
@@ -166,8 +166,8 @@ Replace these method calls:
 | `thread.DeleteAsync()` | Provider-specific cleanup | Use provider client directly |
 
 Return type changes:
-- `IAsyncEnumerable<AgentResponseItem<ChatMessageContent>>` → `AgentResponse`
-- `IAsyncEnumerable<StreamingChatMessageContent>` → `IAsyncEnumerable<AgentResponseUpdate>`
+- `IAsyncEnumerable<AgentResponseItem<ChatMessageContent>>` → `AgentRunResponse`
+- `IAsyncEnumerable<StreamingChatMessageContent>` → `IAsyncEnumerable<AgentRunResponseUpdate>`
 </api_changes>
 
 <configuration_changes>
@@ -191,8 +191,8 @@ Agent Framework changes these behaviors compared to Semantic Kernel Agents:
 1. **Thread Management**: Agent Framework automatically manages thread state. Semantic Kernel required manual thread updates in some scenarios (e.g., OpenAI Responses).
 
 2. **Return Types**:
-   - Non-streaming: Returns single `AgentResponse` instead of `IAsyncEnumerable<AgentResponseItem<ChatMessageContent>>`
-   - Streaming: Returns `IAsyncEnumerable<AgentResponseUpdate>` instead of `IAsyncEnumerable<StreamingChatMessageContent>`
+   - Non-streaming: Returns single `AgentRunResponse` instead of `IAsyncEnumerable<AgentResponseItem<ChatMessageContent>>`
+   - Streaming: Returns `IAsyncEnumerable<AgentRunResponseUpdate>` instead of `IAsyncEnumerable<StreamingChatMessageContent>`
 
 3. **Tool Registration**: Agent Framework uses direct function registration without requiring `[KernelFunction]` attributes.
 
@@ -397,7 +397,7 @@ await foreach (AgentResponseItem<ChatMessageContent> item in agent.InvokeAsync(u
 
 **With this Agent Framework non-streaming pattern:**
 ```csharp
-AgentResponse result = await agent.RunAsync(userInput, thread, options);
+AgentRunResponse result = await agent.RunAsync(userInput, thread, options);
 Console.WriteLine(result);
 ```
 
@@ -411,7 +411,7 @@ await foreach (StreamingChatMessageContent update in agent.InvokeStreamingAsync(
 
 **With this Agent Framework streaming pattern:**
 ```csharp
-await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(userInput, thread, options))
+await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(userInput, thread, options))
 {
     Console.Write(update);
 }
@@ -420,8 +420,8 @@ await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(userInput,
 **Required changes:**
 1. Replace `agent.InvokeAsync()` with `agent.RunAsync()`
 2. Replace `agent.InvokeStreamingAsync()` with `agent.RunStreamingAsync()`
-3. Change return type handling from `IAsyncEnumerable<AgentResponseItem<ChatMessageContent>>` to `AgentResponse`
-4. Change streaming type from `StreamingChatMessageContent` to `AgentResponseUpdate`
+3. Change return type handling from `IAsyncEnumerable<AgentResponseItem<ChatMessageContent>>` to `AgentRunResponse`
+4. Change streaming type from `StreamingChatMessageContent` to `AgentRunResponseUpdate`
 5. Remove `await foreach` for non-streaming calls
 6. Access message content directly from result object instead of iterating
 </api_changes>
@@ -661,7 +661,7 @@ await foreach (var result in agent.InvokeAsync(input, thread, options))
 ```csharp
 ChatClientAgentRunOptions options = new(new ChatOptions { MaxOutputTokens = 1000 });
 
-AgentResponse result = await agent.RunAsync(input, thread, options);
+AgentRunResponse result = await agent.RunAsync(input, thread, options);
 Console.WriteLine(result);
 
 // Access underlying content when needed:
@@ -689,7 +689,7 @@ await foreach (var result in agent.InvokeAsync(input, thread, options))
 
 **With this Agent Framework non-streaming usage pattern:**
 ```csharp
-AgentResponse result = await agent.RunAsync(input, thread, options);
+AgentRunResponse result = await agent.RunAsync(input, thread, options);
 Console.WriteLine($"Tokens: {result.Usage.TotalTokenCount}");
 ```
 
@@ -709,7 +709,7 @@ await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsyn
 
 **With this Agent Framework streaming usage pattern:**
 ```csharp
-await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(input, thread, options))
+await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(input, thread, options))
 {
     if (update.Contents.OfType<UsageContent>().FirstOrDefault() is { } usageContent)
     {

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

@@ -83,7 +83,7 @@ jobs:
               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)) }}
@@ -92,10 +92,10 @@ jobs:
           Write-Host "Launching Azure Cosmos DB Emulator"
           Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
           Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-          echo "COSMOSDB_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
+          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
 
       - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.1.0
+        uses: actions/setup-dotnet@v5.0.1
         with:
           global-json-file: ${{ github.workspace }}/dotnet/global.json
       - name: Build dotnet solutions
@@ -139,7 +139,7 @@ jobs:
           popd
           popd
           rm -rf "$TEMP_DIR"
-
+          
       - name: Run Unit Tests
         shell: bash
         run: |
@@ -147,7 +147,7 @@ jobs:
           for project in $UT_PROJECTS; do
             # 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
@@ -165,8 +165,8 @@ jobs:
           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
@@ -192,10 +192,10 @@ jobs:
           for project in $INTEGRATION_TEST_PROJECTS; do
             # 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"
+              dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx
             else
               echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
             fi
@@ -205,17 +205,20 @@ jobs:
           COSMOSDB_ENDPOINT: https://localhost:8081
           COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
           # OpenAI Models
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          OPENAI_CHAT_MODEL_NAME: ${{ vars.OPENAI_CHAT_MODEL_NAME }}
-          OPENAI_REASONING_MODEL_NAME: ${{ vars.OPENAI_REASONING_MODEL_NAME }}
+          OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
+          OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
+          OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}
           # Azure OpenAI Models
-          AZURE_OPENAI_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
-          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZURE_OPENAI_DEPLOYMENT_NAME }}
-          AZURE_OPENAI_ENDPOINT: ${{ vars.AZURE_OPENAI_ENDPOINT }}
+          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
+          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
           # Azure AI Foundry
-          AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-          AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZURE_AI_MODEL_DEPLOYMENT_NAME }}
-          AZURE_AI_BING_CONNECTION_ID: ${{ vars.AZURE_AI_BING_CONNECTION_ID }}
+          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

.github/workflows/dotnet-integration-tests.yml

@@ -1,102 +0,0 @@
-#
-# Dedicated .NET integration tests workflow, called from the manual integration test orchestrator.
-# Only runs integration test matrix entries (net10.0 and net472).
-#
-
-name: dotnet-integration-tests
-
-on:
-  workflow_call:
-    inputs:
-      checkout-ref:
-        description: "Git ref to checkout (e.g., refs/pull/123/head)"
-        required: true
-        type: string
-
-permissions:
-  contents: read
-  id-token: write
-
-jobs:
-  dotnet-integration-tests:
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - { targetFramework: "net10.0", os: "ubuntu-latest", configuration: Release }
-          - { targetFramework: "net472", os: "windows-latest", configuration: Release }
-    runs-on: ${{ matrix.os }}
-    environment: integration
-    timeout-minutes: 60
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-          sparse-checkout: |
-            .
-            .github
-            dotnet
-            python
-            workflow-samples
-
-      - name: Start Azure Cosmos DB Emulator
-        if: runner.os == 'Windows'
-        shell: pwsh
-        run: |
-          Write-Host "Launching Azure Cosmos DB Emulator"
-          Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"
-          Start-CosmosDbEmulator -NoUI -Key "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-          echo "COSMOS_EMULATOR_AVAILABLE=true" >> $env:GITHUB_ENV
-
-      - name: Setup dotnet
-        uses: actions/setup-dotnet@v5.1.0
-        with:
-          global-json-file: ${{ github.workspace }}/dotnet/global.json
-
-      - name: Build dotnet solutions
-        shell: bash
-        run: |
-          export SOLUTIONS=$(find ./dotnet/ -type f -name "*.slnx" | tr '\n' ' ')
-          for solution in $SOLUTIONS; do
-            dotnet build $solution -c ${{ matrix.configuration }} --warnaserror
-          done
-
-      - name: Azure CLI Login
-        uses: azure/login@v2
-        with:
-          client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-
-      - name: Set up Durable Task and Azure Functions Integration Test Emulators
-        if: matrix.os == 'ubuntu-latest'
-        uses: ./.github/actions/azure-functions-integration-setup
-
-      - name: Run Integration Tests
-        shell: bash
-        run: |
-          export INTEGRATION_TEST_PROJECTS=$(find ./dotnet -type f -name "*IntegrationTests.csproj" | tr '\n' ' ')
-          for project in $INTEGRATION_TEST_PROJECTS; do
-            target_frameworks=$(dotnet msbuild $project -getProperty:TargetFrameworks -p:Configuration=${{ matrix.configuration }} -nologo 2>/dev/null | tr -d '\r')
-            if [[ "$target_frameworks" == *"${{ matrix.targetFramework }}"* ]]; then
-              dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx --filter "Category!=IntegrationDisabled"
-            else
-              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
-            fi
-          done
-        env:
-          COSMOSDB_ENDPOINT: https://localhost:8081
-          COSMOSDB_KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
-          OpenAI__ApiKey: ${{ secrets.OPENAI__APIKEY }}
-          OpenAI__ChatModelId: ${{ vars.OPENAI__CHATMODELID }}
-          OpenAI__ChatReasoningModelId: ${{ vars.OPENAI__CHATREASONINGMODELID }}
-          AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-          AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-          AzureAI__Endpoint: ${{ secrets.AZUREAI__ENDPOINT }}
-          AzureAI__DeploymentName: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
-          AzureAI__BingConnectionId: ${{ vars.AZUREAI__BINGCONECTIONID }}
-          FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
-          FOUNDRY_MEDIA_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MEDIA_DEPLOYMENT_NAME }}
-          FOUNDRY_MODEL_DEPLOYMENT_NAME: ${{ vars.FOUNDRY_MODEL_DEPLOYMENT_NAME }}
-          FOUNDRY_CONNECTION_GROUNDING_TOOL: ${{ vars.FOUNDRY_CONNECTION_GROUNDING_TOOL }}

.github/workflows/integration-tests-manual.yml

@@ -1,134 +0,0 @@
-#
-# This workflow allows manually running integration tests against an open PR or a branch.
-# Go to Actions → "Integration Tests (Manual)" → Run workflow → enter a PR number or branch name.
-#
-# It calls dedicated integration-only workflows (dotnet-integration-tests and python-integration-tests),
-# passing a ref so they check out and test the correct code.
-# Changed paths are detected here so only the relevant test suites run.
-#
-
-name: Integration Tests (Manual)
-
-on:
-  workflow_dispatch:
-    inputs:
-      pr-number:
-        description: "PR number to run integration tests against (leave empty if using branch)"
-        required: false
-        type: string
-        default: ""
-      branch:
-        description: "Branch name to run integration tests against (leave empty if using PR number)"
-        required: false
-        type: string
-        default: ""
-
-permissions:
-  contents: read
-  pull-requests: read
-  id-token: write
-
-concurrency:
-  group: integration-tests-manual-${{ github.event.inputs.pr-number || github.event.inputs.branch }}
-  cancel-in-progress: true
-
-jobs:
-  resolve-ref:
-    name: Resolve ref
-    runs-on: ubuntu-latest
-    outputs:
-      checkout-ref: ${{ steps.resolve.outputs.checkout-ref }}
-      dotnet-changes: ${{ steps.detect-changes.outputs.dotnet }}
-      python-changes: ${{ steps.detect-changes.outputs.python }}
-    steps:
-      - name: Resolve checkout ref
-        id: resolve
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_NUMBER: ${{ github.event.inputs.pr-number }}
-          BRANCH: ${{ github.event.inputs.branch }}
-          REPO: ${{ github.repository }}
-        run: |
-          if [ -n "$PR_NUMBER" ] && [ -n "$BRANCH" ]; then
-            echo "::error::Please provide either a PR number or a branch name, not both."
-            exit 1
-          fi
-
-          if [ -z "$PR_NUMBER" ] && [ -z "$BRANCH" ]; then
-            echo "::error::Please provide either a PR number or a branch name."
-            exit 1
-          fi
-
-          if [ -n "$PR_NUMBER" ]; then
-            if ! echo "$PR_NUMBER" | grep -Eq '^[0-9]+$'; then
-              echo "::error::Invalid PR number. Only numeric values are allowed."
-              exit 1
-            fi
-
-            PR_DATA=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json state)
-            PR_STATE=$(echo "$PR_DATA" | jq -r '.state')
-
-            if [ "$PR_STATE" != "OPEN" ]; then
-              echo "::error::PR #$PR_NUMBER is not open (state: $PR_STATE)"
-              exit 1
-            fi
-
-            echo "checkout-ref=refs/pull/$PR_NUMBER/head" >> "$GITHUB_OUTPUT"
-            echo "Running integration tests for PR #$PR_NUMBER"
-          else
-            if ! echo "$BRANCH" | grep -Eq '^[a-zA-Z0-9_./-]+$'; then
-              echo "::error::Invalid branch name. Only alphanumeric characters, hyphens, underscores, dots, and slashes are allowed."
-              exit 1
-            fi
-
-            echo "checkout-ref=$BRANCH" >> "$GITHUB_OUTPUT"
-            echo "Running integration tests for branch $BRANCH"
-          fi
-
-      - name: Detect changed paths
-        id: detect-changes
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          PR_NUMBER: ${{ github.event.inputs.pr-number }}
-          BRANCH: ${{ github.event.inputs.branch }}
-          REPO: ${{ github.repository }}
-        run: |
-          if [ -n "$PR_NUMBER" ]; then
-            CHANGED_FILES=$(gh pr diff "$PR_NUMBER" --repo "$REPO" --name-only)
-          else
-            # For branches, compare against main using the GitHub API
-            CHANGED_FILES=$(gh api "repos/$REPO/compare/main...$BRANCH" --jq '.files[].filename')
-          fi
-
-          DOTNET_CHANGES=false
-          PYTHON_CHANGES=false
-
-          if echo "$CHANGED_FILES" | grep -q '^dotnet/'; then
-            DOTNET_CHANGES=true
-          fi
-
-          if echo "$CHANGED_FILES" | grep -q '^python/'; then
-            PYTHON_CHANGES=true
-          fi
-
-          echo "dotnet=$DOTNET_CHANGES" >> "$GITHUB_OUTPUT"
-          echo "python=$PYTHON_CHANGES" >> "$GITHUB_OUTPUT"
-          echo "Detected changes — dotnet: $DOTNET_CHANGES, python: $PYTHON_CHANGES"
-
-  dotnet-integration-tests:
-    name: .NET Integration Tests
-    needs: resolve-ref
-    if: needs.resolve-ref.outputs.dotnet-changes == 'true'
-    uses: ./.github/workflows/dotnet-integration-tests.yml
-    with:
-      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
-    secrets: inherit
-
-  python-integration-tests:
-    name: Python Integration Tests
-    needs: resolve-ref
-    if: needs.resolve-ref.outputs.python-changes == 'true'
-    uses: ./.github/workflows/python-integration-tests.yml
-    with:
-      checkout-ref: ${{ needs.resolve-ref.outputs.checkout-ref }}
-    secrets: inherit

.github/workflows/merge-gatekeeper.yml

@@ -29,7 +29,3 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           timeout: 3600
           interval: 30
-          # "Cleanup artifacts", "Agent", "Prepare", and "Upload results" are check runs
-          # created by an org-level GitHub App (MSDO), not by any workflow in this repo.
-          # They are outside our control and their transient failures should not block merges.
-          ignored: CodeQL,CodeQL analysis (csharp),Cleanup artifacts,Agent,Prepare,Upload results

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

@@ -1,383 +0,0 @@
-#!/usr/bin/env python3
-# Copyright (c) Microsoft. All rights reserved.
-"""Check Python test coverage against threshold for enforced targets.
-
-This script parses a Cobertura XML coverage report and enforces a minimum
-coverage threshold on specific targets. Targets can be package names
-(e.g., "packages.core.agent_framework") or individual Python file paths
-(e.g., "packages/core/agent_framework/observability.py").
-
-Non-enforced targets 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 TARGETS CONFIGURATION
-# =============================================================================
-# Add or remove entries from this set to control which targets must meet
-# the coverage threshold. Only these targets will fail the build if below
-# threshold. Other targets are reported for visibility only.
-#
-# Target values can be:
-# - Package paths as they appear in the coverage report
-#   (e.g., "packages.azure-ai.agent_framework_azure_ai")
-# - Python source file paths as they appear in the coverage report
-#   (e.g., "packages/core/agent_framework/observability.py")
-# =============================================================================
-ENFORCED_TARGETS: set[str] = {
-    # Packages
-    "packages.azure-ai.agent_framework_azure_ai",
-    "packages.core.agent_framework",
-    "packages.core.agent_framework._workflows",
-    "packages.purview.agent_framework_purview",
-    "packages.anthropic.agent_framework_anthropic",
-    "packages.azure-ai-search.agent_framework_azure_ai_search",
-    "packages.core.agent_framework.azure",
-    "packages.core.agent_framework.openai",
-    # Individual files (if you want to enforce specific files instead of whole packages)
-    "packages/core/agent_framework/observability.py",
-    # Add more targets here as coverage improves
-}
-
-
-@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 normalize_coverage_path(path: str) -> str:
-    """Normalize coverage paths for reliable matching."""
-    return path.replace("\\", "/").lstrip("./")
-
-
-def parse_coverage_xml(
-    xml_path: str,
-) -> tuple[dict[str, PackageCoverage], 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, files_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] = {}
-    file_stats: dict[str, dict[str, int]] = {}
-
-    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"):
-            file_path = normalize_coverage_path(class_elem.get("filename", ""))
-            if file_path and file_path not in file_stats:
-                file_stats[file_path] = {
-                    "lines_valid": 0,
-                    "lines_covered": 0,
-                    "branches_valid": 0,
-                    "branches_covered": 0,
-                }
-
-            for line in class_elem.findall(".//line"):
-                lines_valid += 1
-                if int(line.get("hits", 0)) > 0:
-                    lines_covered += 1
-
-                if file_path:
-                    file_stats[file_path]["lines_valid"] += 1
-                    if int(line.get("hits", 0)) > 0:
-                        file_stats[file_path]["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])
-                            if file_path:
-                                file_stats[file_path]["branches_covered"] += int(
-                                    coverage_parts[0]
-                                )
-                                file_stats[file_path]["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,
-        )
-
-    files: dict[str, PackageCoverage] = {}
-    for file_path, stats in file_stats.items():
-        lines_valid = stats["lines_valid"]
-        lines_covered = stats["lines_covered"]
-        branches_valid = stats["branches_valid"]
-        branches_covered = stats["branches_covered"]
-
-        files[file_path] = PackageCoverage(
-            name=file_path,
-            line_rate=0 if lines_valid == 0 else lines_covered / lines_valid,
-            branch_rate=0 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, files, 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 target 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],
-    files: 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.
-        files: Dictionary of file path to coverage data, used for per-file enforcement.
-        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}%")
-
-    enforced_targets = {normalize_coverage_path(t) for t in ENFORCED_TARGETS}
-
-    # Package table
-    print("\n" + "-" * 110)
-    print(f"{'Package':<80} {'Lines':<15} {'Line Cov':<15}")
-    print("-" * 110)
-
-    # Sort: enforced package targets first, then alphabetically
-    sorted_packages = sorted(
-        packages.values(),
-        key=lambda p: (p.name not in ENFORCED_TARGETS, p.name),
-    )
-
-    for pkg in sorted_packages:
-        is_enforced = normalize_coverage_path(pkg.name) in enforced_targets
-        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)
-
-    # Enforced file/model entries (if configured)
-    enforced_files = [
-        files[target]
-        for target in sorted(enforced_targets)
-        if target in files and target.endswith(".py")
-    ]
-
-    if enforced_files:
-        print("\nEnforced Files/Models")
-        print("-" * 110)
-        print(f"{'File':<80} {'Lines':<15} {'Line Cov':<15}")
-        print("-" * 110)
-
-        for file_cov in enforced_files:
-            line_cov = format_coverage_value(
-                file_cov.line_coverage_percent, threshold, True
-            )
-            lines_info = f"{file_cov.lines_covered}/{file_cov.lines_valid}"
-            print(f"[ENFORCED] {file_cov.name:<69} {lines_info:<15} {line_cov:<15}")
-
-        print("-" * 110)
-
-
-def check_coverage(xml_path: str, threshold: float) -> bool:
-    """Check if all enforced targets meet the coverage threshold.
-
-    Args:
-        xml_path: Path to the Cobertura XML coverage report.
-        threshold: Minimum required coverage percentage.
-
-    Returns:
-        True if all enforced targets pass, False otherwise.
-    """
-    packages, files, overall_line_rate, overall_branch_rate = parse_coverage_xml(
-        xml_path
-    )
-
-    print_coverage_table(
-        packages, files, threshold, overall_line_rate, overall_branch_rate
-    )
-
-    # Check enforced targets
-    failed_targets: list[str] = []
-    missing_targets: list[str] = []
-
-    for target_name in ENFORCED_TARGETS:
-        normalized_target = normalize_coverage_path(target_name)
-        package_alias = normalized_target.replace("/", ".")
-
-        target_coverage = None
-        if target_name in packages:
-            target_coverage = packages[target_name]
-        elif normalized_target in files:
-            target_coverage = files[normalized_target]
-        elif package_alias in packages:
-            target_coverage = packages[package_alias]
-
-        if target_coverage is None:
-            missing_targets.append(target_name)
-            continue
-
-        if target_coverage.line_coverage_percent < threshold:
-            failed_targets.append(
-                f"{target_name} ({target_coverage.line_coverage_percent:.1f}%)"
-            )
-
-    # Report results
-    if missing_targets:
-        print(
-            f"\n❌ FAILED: Enforced targets not found in coverage report: {', '.join(missing_targets)}"
-        )
-        return False
-
-    if failed_targets:
-        print(
-            f"\n❌ FAILED: The following enforced targets are below {threshold}% coverage threshold:"
-        )
-        for target in failed_targets:
-            print(f"   - {target}")
-        print("\nTo fix: Add more tests to improve coverage for the failing targets.")
-        return False
-
-    if ENFORCED_TARGETS:
-        found_enforced = [
-            target
-            for target in ENFORCED_TARGETS
-            if target in packages or normalize_coverage_path(target) in files
-        ]
-        if found_enforced:
-            print(
-                f"\n✅ PASSED: All enforced targets 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

@@ -12,13 +12,13 @@ env:
   UV_CACHE_DIR: /tmp/.uv-cache
 
 jobs:
-  pre-commit-hooks:
-    name: Pre-commit Hooks
+  pre-commit:
+    name: Checks
     if: "!cancelled()"
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.10", "3.14"]
     runs-on: ubuntu-latest
     continue-on-error: true
     defaults:
@@ -37,106 +37,16 @@ jobs:
           python-version: ${{ matrix.python-version }}
           os: ${{ runner.os }}
         env:
+          # Configure a constant location for the uv cache
           UV_CACHE_DIR: /tmp/.uv-cache
       - uses: actions/cache@v5
         with:
-          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
+          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
         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
+          extra_args: --config python/.pre-commit-config.yaml --all-files
       - name: Run Mypy
         env:
           GITHUB_BASE_REF: ${{ github.event.pull_request.base.ref || github.base_ref || 'main' }}

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

@@ -1,319 +0,0 @@
-#
-# Dedicated Python integration tests workflow, called from the manual integration test orchestrator.
-# Runs all tests (unit + integration) split into parallel jobs by provider.
-#
-# NOTE: This workflow and python-merge-tests.yml share the same set of parallel
-# test jobs. Keep them in sync — when adding, removing, or modifying a job here,
-# apply the same change to python-merge-tests.yml.
-#
-
-name: python-integration-tests
-
-on:
-  workflow_call:
-    inputs:
-      checkout-ref:
-        description: "Git ref to checkout (e.g., refs/pull/123/head)"
-        required: true
-        type: string
-
-permissions:
-  contents: read
-  id-token: write
-
-env:
-  UV_CACHE_DIR: /tmp/.uv-cache
-  UV_PYTHON: "3.13"
-
-jobs:
-  # Unit tests: all non-integration tests across all packages
-  python-tests-unit:
-    name: Python Integration Tests - Unit
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Test with pytest (unit tests only)
-        run: >
-          uv run poe all-tests
-          -m "not integration"
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-
-  # OpenAI integration tests
-  python-tests-openai:
-    name: Python Integration Tests - OpenAI
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    env:
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_EMBEDDINGS_MODEL_ID: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Test with pytest (OpenAI integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/core/tests/openai
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-
-  # Azure OpenAI integration tests
-  python-tests-azure-openai:
-    name: Python Integration Tests - Azure OpenAI
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    env:
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Azure CLI Login
-        uses: azure/login@v2
-        with:
-          client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-      - name: Test with pytest (Azure OpenAI integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/core/tests/azure
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-
-  # Misc integration tests (Anthropic, Ollama, MCP)
-  python-tests-misc-integration:
-    name: Python Integration Tests - Misc
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    env:
-      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
-      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Test with pytest (Anthropic, Ollama, MCP integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/anthropic/tests
-          packages/ollama/tests
-          packages/core/tests/core/test_mcp.py
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-
-  # Azure Functions + Durable Task integration tests
-  python-tests-functions:
-    name: Python Integration Tests - Functions
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    env:
-      UV_PYTHON: "3.10"
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      FUNCTIONS_WORKER_RUNTIME: "python"
-      DURABLE_TASK_SCHEDULER_CONNECTION_STRING: "Endpoint=http://localhost:8080;TaskHub=default;Authentication=None"
-      AzureWebJobsStorage: "UseDevelopmentStorage=true"
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Azure CLI Login
-        uses: azure/login@v2
-        with:
-          client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-      - name: Set up Azure Functions Integration Test Emulators
-        uses: ./.github/actions/azure-functions-integration-setup
-        id: azure-functions-setup
-      - name: Test with pytest (Functions + Durable Task integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/azurefunctions/tests/integration_tests
-          packages/durabletask/tests/integration_tests
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-
-  # Azure AI integration tests
-  python-tests-azure-ai:
-    name: Python Integration Tests - Azure AI
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    env:
-      AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
-      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Azure CLI Login
-        uses: azure/login@v2
-        with:
-          client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-      - name: Test with pytest
-        timeout-minutes: 15
-        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
-
-  # Azure Cosmos integration tests
-  python-tests-cosmos:
-    name: Python Integration Tests - Cosmos
-    runs-on: ubuntu-latest
-    environment: integration
-    timeout-minutes: 60
-    services:
-      cosmosdb:
-        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
-        ports:
-          - 8081:8081
-    env:
-      AZURE_COSMOS_ENDPOINT: "http://localhost:8081/"
-      # Static Azure Cosmos DB emulator key (documented): https://learn.microsoft.com/en-us/azure/cosmos-db/emulator
-      AZURE_COSMOS_KEY: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-      AZURE_COSMOS_DATABASE_NAME: "agent-framework-cosmos-it-db"
-      AZURE_COSMOS_CONTAINER_NAME: "agent-framework-cosmos-it-container"
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          ref: ${{ inputs.checkout-ref }}
-          persist-credentials: false
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Wait for Cosmos DB emulator
-        run: |
-          for i in {1..60}; do
-            if curl --silent --show-error http://localhost:8081/ > /dev/null; then
-              echo "Cosmos DB emulator is ready."
-              exit 0
-            fi
-            sleep 2
-          done
-          echo "Cosmos DB emulator did not become ready in time." >&2
-          exit 1
-      - name: Test with pytest (Cosmos integration)
-        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
-
-  python-integration-tests-check:
-    if: always()
-    runs-on: ubuntu-latest
-    needs:
-      [
-        python-tests-unit,
-        python-tests-openai,
-        python-tests-azure-openai,
-        python-tests-misc-integration,
-        python-tests-functions,
-        python-tests-azure-ai,
-        python-tests-cosmos
-      ]
-    steps:
-      - name: Fail workflow if tests failed
-        if: contains(join(needs.*.result, ','), 'failure')
-        uses: actions/github-script@v8
-        with:
-          script: core.setFailed('Integration Tests Failed!')
-
-      - name: Fail workflow if tests cancelled
-        if: contains(join(needs.*.result, ','), 'cancelled')
-        uses: actions/github-script@v8
-        with:
-          script: core.setFailed('Integration Tests Cancelled!')

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

@@ -1,9 +1,4 @@
 name: Python - Merge - Tests
-#
-# NOTE: This workflow and python-integration-tests.yml share the same set of
-# parallel test jobs. Keep them in sync — when adding, removing, or modifying a
-# job here, apply the same change to python-integration-tests.yml.
-#
 
 on:
   workflow_dispatch:
@@ -15,13 +10,13 @@ on:
     - cron: "0 0 * * *" # Run at midnight UTC daily
 
 permissions:
-  contents: read
+  contents: write
   id-token: write
 
 env:
   # Configure a constant location for the uv cache
   UV_CACHE_DIR: /tmp/.uv-cache
-  UV_PYTHON: "3.13"
+  RUN_INTEGRATION_TESTS: "true"
   RUN_SAMPLES_TESTS: ${{ vars.RUN_SAMPLES_TESTS }}
 
 jobs:
@@ -31,14 +26,7 @@ jobs:
       contents: read
       pull-requests: read
     outputs:
-      pythonChanges: ${{ steps.filter.outputs.python }}
-      coreChanged: ${{ steps.filter.outputs.core }}
-      openaiChanged: ${{ steps.filter.outputs.openai }}
-      azureChanged: ${{ steps.filter.outputs.azure }}
-      miscChanged: ${{ steps.filter.outputs.misc }}
-      functionsChanged: ${{ steps.filter.outputs.functions }}
-      azureAiChanged: ${{ steps.filter.outputs.azure-ai }}
-      cosmosChanged: ${{ steps.filter.outputs.cosmos }}
+      pythonChanges: ${{ steps.filter.outputs.python}}
     steps:
       - uses: actions/checkout@v6
       - uses: dorny/paths-filter@v3
@@ -47,29 +35,6 @@ jobs:
           filters: |
             python:
               - 'python/**'
-            core:
-              - 'python/packages/core/agent_framework/_*.py'
-              - 'python/packages/core/agent_framework/_workflows/**'
-              - 'python/packages/core/agent_framework/exceptions.py'
-              - 'python/packages/core/agent_framework/observability.py'
-            openai:
-              - 'python/packages/core/agent_framework/openai/**'
-              - 'python/packages/core/tests/openai/**'
-            azure:
-              - 'python/packages/core/agent_framework/azure/**'
-              - 'python/packages/core/tests/azure/**'
-            misc:
-              - 'python/packages/anthropic/**'
-              - 'python/packages/ollama/**'
-              - 'python/packages/core/agent_framework/_mcp.py'
-              - 'python/packages/core/tests/core/test_mcp.py'
-            functions:
-              - 'python/packages/azurefunctions/**'
-              - 'python/packages/durabletask/**'
-            azure-ai:
-              - 'python/packages/azure-ai/**'
-            cosmos:
-              - 'python/packages/azure-cosmos/**'
       # run only if 'python' files were changed
       - name: python tests
         if: steps.filter.outputs.python == 'true'
@@ -78,226 +43,34 @@ jobs:
       - name: not python tests
         if: steps.filter.outputs.python != 'true'
         run: echo "NOT python file"
-  # Unit tests: always run all non-integration tests across all packages
-  python-tests-unit:
-    name: Python Tests - Unit
+  python-tests-core:
+    name: Python Tests - Core
     needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true'
-    runs-on: ubuntu-latest
-    environment: integration
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Test with pytest (unit tests only)
-        run: >
-          uv run poe all-tests
-          -m "not integration"
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Surface failing tests
-        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
-        with:
-          path: ./python/**.xml
-          summary: true
-          display-options: fEX
-          fail-on-empty: false
-          title: Unit test results
-
-  # OpenAI integration tests
-  python-tests-openai:
-    name: Python Tests - OpenAI Integration
-    needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.openaiChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
+    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
+    runs-on: ${{ matrix.os }}
+    environment: ${{ matrix.environment }}
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.10"]
+        os: [ubuntu-latest]
+        environment: ["integration"]
     env:
+      UV_PYTHON: ${{ matrix.python-version }}
       OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
       OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_EMBEDDINGS_MODEL_ID: ${{ vars.OPENAI_EMBEDDING_MODEL_ID }}
       OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Test with pytest (OpenAI integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/core/tests/openai
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Test OpenAI samples
-        timeout-minutes: 10
-        if: env.RUN_SAMPLES_TESTS == 'true'
-        run: uv run pytest tests/samples/ -m "openai"
-        working-directory: ./python
-      - name: Surface failing tests
-        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
-        with:
-          path: ./python/**.xml
-          summary: true
-          display-options: fEX
-          fail-on-empty: false
-          title: OpenAI integration test results
-
-  # Azure OpenAI integration tests
-  python-tests-azure-openai:
-    name: Python Tests - Azure OpenAI Integration
-    needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.azureChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__EMBEDDINGDEPLOYMENTNAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Azure CLI Login
-        if: github.event_name != 'pull_request'
-        uses: azure/login@v2
-        with:
-          client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-      - name: Test with pytest (Azure OpenAI integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/core/tests/azure
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Test Azure samples
-        timeout-minutes: 10
-        if: env.RUN_SAMPLES_TESTS == 'true'
-        run: uv run pytest tests/samples/ -m "azure"
-        working-directory: ./python
-      - name: Surface failing tests
-        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
-        with:
-          path: ./python/**.xml
-          summary: true
-          display-options: fEX
-          fail-on-empty: false
-          title: Azure OpenAI integration test results
-
-  # Misc integration tests (Anthropic, Ollama, MCP)
-  python-tests-misc-integration:
-    name: Python Tests - Misc Integration
-    needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.miscChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
       ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
       ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
-      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Test with pytest (Anthropic, Ollama, MCP integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/anthropic/tests
-          packages/ollama/tests
-          packages/core/tests/core/test_mcp.py
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Surface failing tests
-        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
-        with:
-          path: ./python/**.xml
-          summary: true
-          display-options: fEX
-          fail-on-empty: false
-          title: Misc integration test results
-
-  # Azure Functions + Durable Task integration tests
-  python-tests-functions:
-    name: Python Tests - Functions Integration
-    needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.functionsChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      UV_PYTHON: "3.10"
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
       AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
       AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
       AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
+      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
@@ -307,8 +80,11 @@ jobs:
         id: python-setup
         uses: ./.github/actions/python-setup
         with:
-          python-version: ${{ env.UV_PYTHON }}
+          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
@@ -319,15 +95,14 @@ jobs:
       - name: Set up Azure Functions Integration Test Emulators
         uses: ./.github/actions/azure-functions-integration-setup
         id: azure-functions-setup
-      - name: Test with pytest (Functions + Durable Task integration)
-        run: >
-          uv run pytest --import-mode=importlib
-          packages/azurefunctions/tests/integration_tests
-          packages/durabletask/tests/integration_tests
-          -m integration
-          -n logical --dist worksteal
-          --timeout=120 --session-timeout=900 --timeout_method thread
-          --retries 2 --retry-delay 5
+      - name: Test with pytest
+        timeout-minutes: 10
+        run: uv run poe all-tests -n logical --dist loadfile --dist worksteal --timeout 300 --retries 3 --retry-delay 10
+        working-directory: ./python
+      - name: 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: Surface failing tests
         if: always()
@@ -337,20 +112,22 @@ jobs:
           summary: true
           display-options: fEX
           fail-on-empty: false
-          title: Functions integration test results
+          title: Test results
 
   python-tests-azure-ai:
     name: Python Tests - Azure AI
     needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.azureAiChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
+    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 }}
       AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
       AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
       LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
@@ -363,8 +140,11 @@ jobs:
         id: python-setup
         uses: ./.github/actions/python-setup
         with:
-          python-version: ${{ env.UV_PYTHON }}
+          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
@@ -373,8 +153,8 @@ jobs:
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
       - name: Test with pytest
-        timeout-minutes: 15
-        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
+        timeout-minutes: 10
+        run: uv run --directory packages/azure-ai poe integration-tests -n logical --dist loadfile --dist worksteal --timeout 300 --retries 3 --retry-delay 10
         working-directory: ./python
       - name: Test Azure AI samples
         timeout-minutes: 10
@@ -393,78 +173,16 @@ jobs:
 
   # TODO: Add python-tests-lab
 
-  # Azure Cosmos integration tests
-  python-tests-cosmos:
-    name: Python Tests - Cosmos Integration
-    needs: paths-filter
-    if: >
-      github.event_name != 'pull_request' &&
-      needs.paths-filter.outputs.pythonChanges == 'true' &&
-      (github.event_name != 'merge_group' ||
-       needs.paths-filter.outputs.cosmosChanged == 'true' ||
-       needs.paths-filter.outputs.coreChanged == 'true')
-    runs-on: ubuntu-latest
-    environment: integration
-    services:
-      cosmosdb:
-        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
-        ports:
-          - 8081:8081
-    env:
-      AZURE_COSMOS_ENDPOINT: "http://localhost:8081/"
-      # Static Azure Cosmos DB emulator key (documented): https://learn.microsoft.com/en-us/azure/cosmos-db/emulator
-      AZURE_COSMOS_KEY: "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-      AZURE_COSMOS_DATABASE_NAME: "agent-framework-cosmos-it-db"
-      AZURE_COSMOS_CONTAINER_NAME: "agent-framework-cosmos-it-container"
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ env.UV_PYTHON }}
-          os: ${{ runner.os }}
-      - name: Wait for Cosmos DB emulator
-        run: |
-          for i in {1..60}; do
-            if curl --silent --show-error http://localhost:8081/ > /dev/null; then
-              echo "Cosmos DB emulator is ready."
-              exit 0
-            fi
-            sleep 2
-          done
-          echo "Cosmos DB emulator did not become ready in time." >&2
-          exit 1
-      - name: Test with pytest (Cosmos integration)
-        run: uv run --directory packages/azure-cosmos poe integration-tests -n logical --dist worksteal --timeout=120 --session-timeout=900 --timeout_method thread --retries 2 --retry-delay 5
-        working-directory: ./python
-      - name: Surface failing tests
-        if: always()
-        uses: pmeier/pytest-results-action@v0.7.2
-        with:
-          path: ./python/**.xml
-          summary: true
-          display-options: fEX
-          fail-on-empty: false
-          title: Cosmos integration test results
-
   python-integration-tests-check:
     if: always()
     runs-on: ubuntu-latest
     needs:
       [
-        python-tests-unit,
-        python-tests-openai,
-        python-tests-azure-openai,
-        python-tests-misc-integration,
-        python-tests-functions,
-        python-tests-azure-ai,
-        python-tests-cosmos,
+        python-tests-core,
+        python-tests-azure-ai
       ]
     steps:
+
       - name: Fail workflow if tests failed
         id: check_tests_failed
         if: contains(join(needs.*.result, ','), 'failure')

.github/workflows/python-sample-validation.yml

@@ -1,302 +0,0 @@
-name: Python - Sample Validation
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: "0 0 * * *" # Run at midnight UTC daily
-
-env:
-  # Configure a constant location for the uv cache
-  UV_CACHE_DIR: /tmp/.uv-cache
-  # GitHub Copilot configuration
-  GITHUB_COPILOT_MODEL: claude-opus-4.6
-  COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
-
-permissions:
-  contents: read
-  id-token: write
-
-jobs:
-  validate-01-get-started:
-    name: Validate 01-get-started
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Required configuration for get-started samples
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 01-get-started --save-report --report-name 01-get-started
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: validation-report-01-get-started
-          path: python/scripts/sample_validation/reports/
-
-  validate-02-agents:
-    name: Validate 02-agents
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # OpenAI configuration
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      # Observability
-      ENABLE_INSTRUMENTATION: "true"
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 02-agents --save-report --report-name 02-agents
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: validation-report-02-agents
-          path: python/scripts/sample_validation/reports/
-
-  validate-03-workflows:
-    name: Validate 03-workflows
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 03-workflows --save-report --report-name 03-workflows
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: validation-report-03-workflows
-          path: python/scripts/sample_validation/reports/
-
-  validate-04-hosting:
-    name: Validate 04-hosting
-    if: false  # Temporarily disabled because of sample complexity
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # A2A configuration
-      A2A_AGENT_HOST: http://localhost:5001/
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 04-hosting --save-report --report-name 04-hosting
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: validation-report-04-hosting
-          path: python/scripts/sample_validation/reports/
-
-  validate-05-end-to-end:
-    name: Validate 05-end-to-end
-    if: false  # Temporarily disabled because of sample complexity
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure AI Search (for evaluation samples)
-      AZURE_SEARCH_ENDPOINT: ${{ secrets.AZURE_SEARCH_ENDPOINT }}
-      AZURE_SEARCH_API_KEY: ${{ secrets.AZURE_SEARCH_API_KEY }}
-      AZURE_SEARCH_INDEX_NAME: ${{ secrets.AZURE_SEARCH_INDEX_NAME }}
-      # Evaluation sample
-      AZURE_AI_MODEL_DEPLOYMENT_NAME_WORKFLOW: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir 05-end-to-end --save-report --report-name 05-end-to-end
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: validation-report-05-end-to-end
-          path: python/scripts/sample_validation/reports/
-
-  validate-autogen-migration:
-    name: Validate autogen-migration
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      # OpenAI configuration
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir autogen-migration --save-report --report-name autogen-migration
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: validation-report-autogen-migration
-          path: python/scripts/sample_validation/reports/
-
-  validate-semantic-kernel-migration:
-    name: Validate semantic-kernel-migration
-    runs-on: ubuntu-latest
-    environment: integration
-    env:
-      # Azure AI configuration
-      AZURE_AI_PROJECT_ENDPOINT: ${{ vars.AZURE_AI_PROJECT_ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # Azure OpenAI configuration
-      AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
-      AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
-      AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
-      # OpenAI configuration
-      OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
-      OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
-      # Copilot Studio
-      COPILOTSTUDIOAGENT__ENVIRONMENTID: ${{ secrets.COPILOTSTUDIOAGENT__ENVIRONMENTID }}
-      COPILOTSTUDIOAGENT__SCHEMANAME: ${{ secrets.COPILOTSTUDIOAGENT__SCHEMANAME }}
-      COPILOTSTUDIOAGENT__TENANTID: ${{ secrets.COPILOTSTUDIOAGENT__TENANTID }}
-      COPILOTSTUDIOAGENT__AGENTAPPID: ${{ secrets.COPILOTSTUDIOAGENT__AGENTAPPID }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup environment
-        uses: ./.github/actions/sample-validation-setup
-        with:
-          azure-client-id: ${{ secrets.AZURE_CLIENT_ID }}
-          azure-tenant-id: ${{ secrets.AZURE_TENANT_ID }}
-          azure-subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
-          os: ${{ runner.os }}
-
-      - name: Run sample validation
-        run: |
-          cd scripts && uv run python -m sample_validation --subdir semantic-kernel-migration --save-report --report-name semantic-kernel-migration
-
-      - name: Upload validation report
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: validation-report-semantic-kernel-migration
-          path: python/scripts/sample_validation/reports/

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

@@ -34,16 +34,9 @@ jobs:
         # 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"
+          PR_NUMBER=$(cat pr_number)
+          echo "PR number: $PR_NUMBER"
+          echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
       - name: Pytest coverage comment
         id: coverageComment
         uses: MishaKav/pytest-coverage-comment@v1.2.0

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

@@ -9,8 +9,6 @@ on:
 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:
@@ -39,8 +37,6 @@ jobs:
           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:

.gitignore

@@ -199,22 +199,22 @@ temp*/
 .tmp/
 .temp/
 
+agents.md
+
 # 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*
+*/__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
@@ -226,4 +226,3 @@ local.settings.json
 
 # Database files
 *.db
-python/dotnet-ref

README.md

@@ -53,7 +53,7 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 ### ✨ **Highlights**
 
 - **Graph-based Workflows**: Connect agents and deterministic functions using data flows with streaming, checkpointing, human-in-the-loop, and time-travel capabilities
-  - [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/03-workflows/)
+  - [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
@@ -73,11 +73,11 @@ Still have questions? Join our [weekly office hours](./COMMUNITY.md#public-commu
 - **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
   - [Python packages](./python/packages/) | [.NET source](./dotnet/src/)
 - **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging
-  - [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/02-agents/AgentOpenTelemetry/)
+  - [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/02-agents/providers/) | [.NET examples](./dotnet/samples/02-agents/AgentProviders/)
+  - [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/02-agents/middleware/) | [.NET middleware](./dotnet/samples/02-agents/Agents/Agent_Step11_Middleware/)
+  - [Python middleware](./python/samples/getting_started/middleware/) | [.NET middleware](./dotnet/samples/GettingStarted/Agents/Agent_Step14_Middleware/)
 
 ### 💬 **We want your feedback!**
 
@@ -108,7 +108,7 @@ async def main():
         # 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(
+    ).create_agent(
         name="HaikuBot",
         instructions="You are an upbeat assistant that writes beautifully.",
     )
@@ -125,14 +125,13 @@ Create a simple Agent, using OpenAI Responses, that writes a haiku about the Mic
 
 ```c#
 // dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
-using Microsoft.Agents.AI;
+using System;
 using OpenAI;
-using OpenAI.Responses;
 
 // Replace the <apikey> with your OpenAI API key.
 var agent = new OpenAIClient("<apikey>")
-    .GetResponsesClient("gpt-4o-mini")
-    .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+    .GetOpenAIResponseClient("gpt-4o-mini")
+    .CreateAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```
@@ -143,18 +142,15 @@ Create a simple Agent, using Azure OpenAI Responses with token based auth, that
 // dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
 // dotnet add package Azure.Identity
 // Use `az login` to authenticate with Azure CLI
-using System.ClientModel.Primitives;
-using Azure.Identity;
-using Microsoft.Agents.AI;
+using System;
 using OpenAI;
-using OpenAI.Responses;
 
 // Replace <resource> and gpt-4o-mini with your Azure OpenAI resource name and deployment name.
 var agent = new OpenAIClient(
     new BearerTokenPolicy(new AzureCliCredential(), "https://ai.azure.com/.default"),
     new OpenAIClientOptions() { Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1") })
-    .GetResponsesClient("gpt-4o-mini")
-    .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+    .GetOpenAIResponseClient("gpt-4o-mini")
+    .CreateAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```
@@ -163,15 +159,15 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
 
 ### Python
 
-- [Getting Started with Agents](./python/samples/01-get-started): progressive tutorial from hello-world to hosting
-- [Agent Concepts](./python/samples/02-agents): deep-dive samples by topic (tools, middleware, providers, etc.)
-- [Getting Started with Workflows](./python/samples/03-workflows): workflow creation and integration with agents
+- [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
 
 ### .NET
 
-- [Getting Started with Agents](./dotnet/samples/02-agents/Agents): basic agent creation and tool usage
-- [Agent Provider Samples](./dotnet/samples/02-agents/AgentProviders): samples showing different agent providers
-- [Workflow Samples](./dotnet/samples/03-workflows): advanced multi-agent patterns and workflow orchestration
+- [Getting Started 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
 

agent-samples/README.md

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

agent-samples/openai/OpenAIResponses.yaml

@@ -11,7 +11,7 @@ model:
         topP: 0.95
     connection:
         kind: key
-        apiKey: =Env.OPENAI_API_KEY
+        apiKey: =Env.OPENAI_APIKEY
 outputSchema:
     properties:
         language:

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

@@ -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 `AgentResponse.Messages` property while Secondary updates are in a new `AgentResponse.Updates` property.
-`AgentResponse.Text` returns the Primary content text.
+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.
 
 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<AgentResponse> RunAsync(
+    public abstract Task<AgentRunResponse> RunAsync(
         IReadOnlyCollection<ChatMessage> messages,
         AgentThread? thread = null,
         AgentRunOptions? options = null,
         CancellationToken cancellationToken = default);
 
-    public abstract IAsyncEnumerable<AgentResponseUpdate> RunStreamingAsync(
+    public abstract IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(
         IReadOnlyCollection<ChatMessage> messages,
         AgentThread? thread = null,
         AgentRunOptions? options = null,
         CancellationToken cancellationToken = default);
 }
 
-class AgentResponse : ChatResponse
+class AgentRunResponse : ChatResponse
 {
 }
 
-public class AgentResponseUpdate : ChatResponseUpdate
+public class AgentRunResponseUpdate : 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<AgentResponse> RunAsync(
+    public abstract Task<AgentRunResponse> RunAsync(
         IReadOnlyCollection<ChatMessage> messages,
         AgentThread? thread = null,
         AgentRunOptions? options = null,
         CancellationToken cancellationToken = default);
 
-    public abstract IAsyncEnumerable<AgentResponseUpdate> RunStreamingAsync(
+    public abstract IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(
         IReadOnlyCollection<ChatMessage> messages,
         AgentThread? thread = null,
         AgentRunOptions? options = null,
         CancellationToken cancellationToken = default);
 }
 
-class AgentResponse // Compare with ChatResponse
+class AgentRunResponse // Compare with ChatResponse
 {
     public string Text { get; } // Aggregation of TextContent from messages.
 
@@ -294,12 +294,12 @@ class AgentResponse // Compare with ChatResponse
     public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
 }
 
-// Not Included in AgentResponse compared to ChatResponse
+// Not Included in AgentRunResponse compared to ChatResponse
 public ChatFinishReason? FinishReason { get; set; }
 public string? ConversationId { get; set; }
 public string? ModelId { get; set; }
 
-public class AgentResponseUpdate // Compare with ChatResponseUpdate
+public class AgentRunResponseUpdate // Compare with ChatResponseUpdate
 {
     public string Text { get; } // Aggregation of TextContent from Contents.
 
@@ -317,7 +317,7 @@ public class AgentResponseUpdate // Compare with ChatResponseUpdate
     public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
 }
 
-// Not Included in AgentResponseUpdate compared to ChatResponseUpdate
+// Not Included in AgentRunResponseUpdate 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 AgentResponse
+class AgentRunResponse
 {
     ...
     public AgentRun RunReference { get; set; } // Reference to long running process
@@ -368,7 +368,7 @@ class AgentResponse
 }
 
 
-public class AgentResponseUpdate
+public class AgentRunResponseUpdate
 {
     ...
     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 `AgentResponse<T>`, that allows us to get the agent result already deserialized into our preferred type.
+We would add a generic version of `AgentRunResponse<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; }
 }
 
-AgentResponse<Movie[]> response = agent.RunAsync<Movie[]>("What are the top 3 children's movies of the 80s.");
+AgentRunResponse<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
-AgentResponse response = agent.RunAsync("What are the top 3 children's movies of the 80s.");
+AgentRunResponse 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 `AgentResponse`.
+We will however add support for easily extracting a structured output type from the `AgentRunResponse`.
 
 ## Addendum 1: AIContext Derived Types for different response types / Gap Analysis (Work in progress)
 
@@ -498,7 +498,7 @@ We need to decide what AIContent types, each agent response type will be mapped
 | Google ADK | **Approach 1** Both [input and output schemas can be specified for LLM Agents](https://google.github.io/adk-docs/agents/llm-agents/#structuring-data-input_schema-output_schema-output_key) at construction time. This option is specific to this agent type and other agent types do not necessarily support |
 | AWS (Strands) | **Approach 2** Supports a special invocation method called [structured_output](https://strandsagents.com/latest/documentation/docs/api-reference/python/agent/agent/#strands.agent.agent.Agent.structured_output) |
 | LangGraph | **Approach 1** Supports [configuring an agent](https://langchain-ai.github.io/langgraph/agents/agents/?h=structured#6-configure-structured-output) at agent construction time, and a [structured response](https://langchain-ai.github.io/langgraph/agents/run_agents/#output-format) can be retrieved as a special property on the agent response |
-| Agno | **Approach 1** Supports [configuring an agent](https://docs.agno.com/input-output/structured-output/agent) at agent construction time |
+| 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://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 |
 

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

@@ -54,7 +54,7 @@ The table below represents the majority of the naming changes discussed in issue
 | *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 |
+| AgentRunResponse & AgentRunResponseUpdate | AgentResponse & AgentResponseUpdate | rejected | Rejected, because it is the response to a run invocation and AgentResponse is too generic. | None |
 | *Content | * | rejected | Rejected other content type renames (removing `Content` suffix) because it would reduce clarity and discoverability. | Item was also considered, but rejected as it is very similar to Content, but would be inconsistent with dotnet. |
 | ChatResponse & ChatResponseUpdate | Response & ResponseUpdate | rejected | Rejected, because Response is too generic. | None |
 

docs/decisions/0006-userapproval.md

@@ -161,11 +161,11 @@ while (response.ApprovalRequests.Count > 0)
     response = await agent.RunAsync(messages, thread);
 }
 
-class AgentResponse
+class AgentRunResponse
 {
     ...
 
-    // A new property on AgentResponse to aggregate the ApprovalRequestContent items from
+    // A new property on AgentRunResponse to aggregate the ApprovalRequestContent items from
     // the response messages (Similar to the Text property).
     public IEnumerable<ApprovalRequestContent> ApprovalRequests { get; set; }
 
@@ -251,11 +251,11 @@ while (response.UserInputRequests.Any())
     response = await agent.RunAsync(messages, thread);
 }
 
-class AgentResponse
+class AgentRunResponse
 {
     ...
 
-    // A new property on AgentResponse to aggregate the UserInputRequestContent items from
+    // A new property on AgentRunResponse to aggregate the UserInputRequestContent items from
     // the response messages (Similar to the Text property).
     public IReadOnlyList<UserInputRequestContent> UserInputRequests { get; set; }
 
@@ -366,11 +366,11 @@ while (response.UserInputRequests.Any())
     response = await agent.RunAsync(messages, thread);
 }
 
-class AgentResponse
+class AgentRunResponse
 {
     ...
 
-    // A new property on AgentResponse to aggregate the UserInputRequestContent items from
+    // A new property on AgentRunResponse to aggregate the UserInputRequestContent items from
     // the response messages (Similar to the Text property).
     public IEnumerable<UserInputRequestContent> UserInputRequests { get; set; }
 

docs/decisions/0007-agent-filtering-middleware.md

@@ -115,7 +115,7 @@ public class AIAgent
         }
     }
 
-    public async Task<AgentResponse> RunAsync(
+    public async Task<AgentRunResponse> RunAsync(
         IReadOnlyCollection<ChatMessage> messages,
         AgentThread? thread = null,
         AgentRunOptions? options = null,
@@ -135,7 +135,7 @@ public class AIAgent
         return context.Response ?? throw new InvalidOperationException("Agent execution did not produce a response");
     }
 
-    protected abstract Task<AgentResponse> ExecuteCoreLogicAsync(
+    protected abstract Task<AgentRunResponse> ExecuteCoreLogicAsync(
         IReadOnlyCollection<ChatMessage> messages,
         AgentThread? thread,
         AgentRunOptions? options,
@@ -190,7 +190,7 @@ internal sealed class GuardrailCallbackAgent : DelegatingAIAgent
 
     public GuardrailCallbackAgent(AIAgent innerAgent) : base(innerAgent) { }
 
-    public override async Task<AgentResponse> RunAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
+    public override async Task<AgentRunResponse> RunAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
     {
         var filteredMessages = this.FilterMessages(messages);
         Console.WriteLine($"Guardrail Middleware - Filtered messages: {new ChatResponse(filteredMessages).Text}");
@@ -202,14 +202,14 @@ internal sealed class GuardrailCallbackAgent : DelegatingAIAgent
         return response;
     }
 
-    public override async IAsyncEnumerable<AgentResponseUpdate> RunStreamingAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    public override async IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
     {
         var filteredMessages = this.FilterMessages(messages);
         await foreach (var update in this.InnerAgent.RunStreamingAsync(filteredMessages, thread, options, cancellationToken))
         {
             if (update.Text != null)
             {
-                yield return new AgentResponseUpdate(update.Role, this.FilterContent(update.Text));
+                yield return new AgentRunResponseUpdate(update.Role, this.FilterContent(update.Text));
             }
             else
             {
@@ -252,7 +252,7 @@ internal sealed class RunningCallbackHandlerAgent : DelegatingAIAgent
         this._func = func;
     }
 
-    public override async Task<AgentResponse> RunAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
+    public override async Task<AgentRunResponse> RunAsync(IEnumerable<ChatMessage> messages, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
     {
         var context = new AgentInvokeCallbackContext(this, messages, thread, options, isStreaming: false, cancellationToken);
 
@@ -469,7 +469,7 @@ public sealed class CallbackEnabledAgent : DelegatingAIAgent
         this._callbacksProcessor = callbackMiddlewareProcessor ?? new();
     }
 
-    public override async Task<AgentResponse> RunAsync(
+    public override async Task<AgentRunResponse> RunAsync(
         IEnumerable<ChatMessage> messages,
         AgentThread? thread = null,
         AgentRunOptions? options = null,
@@ -541,7 +541,7 @@ public abstract class AgentContext
 public class AgentRunContext : AgentContext
 {
     public IList<ChatMessage> Messages { get; set; }
-    public AgentResponse? Response { get; set; }
+    public AgentRunResponse? Response { get; set; }
     public AgentThread? Thread { get; }
 
     public AgentRunContext(AIAgent agent, IList<ChatMessage> messages, AgentThread? thread, AgentRunOptions? options)

docs/decisions/0009-support-long-running-operations.md

@@ -687,7 +687,7 @@ This section considers different options for exposing the `RunId`, `Status`, and
 #### 4.1. As AIContent
 
 The `AsyncRunContent` class will represent a long-running operation initiated and managed by an agent/LLM.
-Items of this content type will be returned in a chat message as part of the `AgentResponse` or `ChatResponse`
+Items of this content type will be returned in a chat message as part of the `AgentRunResponse` or `ChatResponse`
 response to represent the long-running operation.
 
 The `AsyncRunContent` class has two properties: `RunId` and `Status`. The `RunId` identifies the 
@@ -1162,29 +1162,29 @@ For cancellation and deletion of long-running operations, new methods will be ad
 public abstract class AIAgent
 {
     // Existing methods...
-    public Task<AgentResponse> RunAsync(string message, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) { ... }
-    public IAsyncEnumerable<AgentResponseUpdate> RunStreamingAsync(string message, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) { ... }
+    public Task<AgentRunResponse> RunAsync(string message, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) { ... }
+    public IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(string message, AgentThread? thread = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default) { ... }
 
     // New methods for uncommon operations
-    public virtual Task<AgentResponse?> CancelRunAsync(string id, AgentCancelRunOptions? options = null, CancellationToken cancellationToken = default)
+    public virtual Task<AgentRunResponse?> CancelRunAsync(string id, AgentCancelRunOptions? options = null, CancellationToken cancellationToken = default)
     {
-        return Task.FromResult<AgentResponse?>(null);
+        return Task.FromResult<AgentRunResponse?>(null);
     }
 
-    public virtual Task<AgentResponse?> DeleteRunAsync(string id, AgentDeleteRunOptions? options = null, CancellationToken cancellationToken = default)
+    public virtual Task<AgentRunResponse?> DeleteRunAsync(string id, AgentDeleteRunOptions? options = null, CancellationToken cancellationToken = default)
     {
-        return Task.FromResult<AgentResponse?>(null);
+        return Task.FromResult<AgentRunResponse?>(null);
     }
 }
 
 // Agent that supports update and cancellation
 public class CustomAgent : AIAgent
 {
-    public override async Task<AgentResponse?> CancelRunAsync(string id, AgentCancelRunOptions? options = null, CancellationToken cancellationToken = default)
+    public override async Task<AgentRunResponse?> CancelRunAsync(string id, AgentCancelRunOptions? options = null, CancellationToken cancellationToken = default)
     {
         var response = await this._client.CancelRunAsync(id, options?.Thread?.ConversationId);
 
-        return ConvertToAgentResponse(response); 
+        return ConvertToAgentRunResponse(response); 
     }
 
     // No overload for DeleteRunAsync as it's not supported by the underlying API
@@ -1195,7 +1195,7 @@ AIAgent agent = new CustomAgent();
 
 AgentThread thread = agent.GetNewThread();
 
-AgentResponse response = await agent.RunAsync("What is the capital of France?");
+AgentRunResponse response = await agent.RunAsync("What is the capital of France?");
 
 response = await agent.CancelRunAsync(response.ResponseId, new AgentCancelRunOptions { Thread = thread });
 ```
@@ -1251,10 +1251,10 @@ public class AgentRunOptions
 AIAgent agent = ...; // Get an instance of an AIAgent
 
 // Start a long-running execution for the prompt if supported by the underlying API
-AgentResponse response = await agent.RunAsync("<prompt>", new AgentRunOptions { AllowLongRunningResponses = true });
+AgentRunResponse response = await agent.RunAsync("<prompt>", new AgentRunOptions { AllowLongRunningResponses = true });
 
 // Start a quick prompt
-AgentResponse response = await agent.RunAsync("<prompt>");
+AgentRunResponse response = await agent.RunAsync("<prompt>");
 ```
 
 **Pros:** 
@@ -1279,7 +1279,7 @@ Below are the details of the option selected for chat clients that is also selec
 #### 3.1 Continuation Token of a Custom Type
 
 This option suggests using `ContinuationToken` to encapsulate all properties representing a long-running operation. The continuation token will be returned by agents in the 
-`ContinuationToken` property of the `AgentResponse` and `AgentResponseUpdate` responses to indicate that the response is part of a long-running operation. A null value 
+`ContinuationToken` property of the `AgentRunResponse` and `AgentRunResponseUpdate` responses to indicate that the response is part of a long-running operation. A null value 
 of the property will indicate that the response is not part of a long-running operation or the long-running operation has been completed. Callers will set the token in the
 `ContinuationToken` property of the `AgentRunOptions` class in follow-up calls to the `Run{Streaming}Async` methods to indicate that they want to "continue" the long-running
 operation identified by the token.
@@ -1313,18 +1313,18 @@ public class AgentRunOptions
     public ResponseContinuationToken? ContinuationToken { get; set; }
 }
 
-public class AgentResponse
+public class AgentRunResponse
 {
     public ResponseContinuationToken? ContinuationToken { get; }
 }
  
-public class AgentResponseUpdate
+public class AgentRunResponseUpdate
 {
     public ResponseContinuationToken? ContinuationToken { get; }
 }
 
 // Usage example
-AgentResponse response = await agent.RunAsync("What is the capital of France?");
+AgentRunResponse response = await agent.RunAsync("What is the capital of France?");
 
 AgentRunOptions options = new() { ContinuationToken = response.ContinuationToken };
 

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

@@ -36,7 +36,7 @@ Chosen option: "Current approach with internal event types and framework-native
 
 - 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
+- Uses existing framework types (AgentRunResponseUpdate, ChatMessage) for public API
 - Focuses on core text streaming functionality
 - Leverages existing properties (ConversationId, ResponseId, ErrorContent) instead of custom types
 - Provides bidirectional client and server support
@@ -69,7 +69,7 @@ Chosen option: "Current approach with internal event types and framework-native
 
 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`)
+4. **Bidirectional Conversion Architecture** - Symmetric conversion logic in shared namespace compiled into both packages for server (`AgentRunResponseUpdate` → AG-UI events) and client (AG-UI events → `AgentRunResponseUpdate`)
 
 5. **Thread Management** - `AGUIAgentThread` stores only `ThreadId` with thread ID communicated via `ConversationId`; applications manage persistence for parity with other implementations and to be compliant with the protocol. Future extensions will support having the server manage the conversation.
 

docs/decisions/0011-create-get-agent-api.md

@@ -1,368 +0,0 @@
----
-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

@@ -1,129 +0,0 @@
----
-# 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/02-agents/typed_options.py) for a complete example demonstrating the usage of typed options with custom extensions.

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

@@ -1,258 +0,0 @@
----
-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

@@ -1,423 +0,0 @@
----
-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

@@ -1,147 +0,0 @@
----
-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/decisions/0016-structured-output.md

@@ -1,658 +0,0 @@
----
-status: proposed
-contact: sergeymenshykh
-date: 2026-01-22
-deciders: rbarreto, westey-m, stephentoub
-informed: {}
----
-
-# Structured Output
-
-Structured output is a valuable aspect of any agent system, since it forces an agent to produce output in a required format that may include required fields.
-This allows easily turning unstructured data into structured data using a general-purpose language model.
-
-## Context and Problem Statement
-
-Structured output is currently supported only by `ChatClientAgent` and can be configured in two ways:
-
-**Approach 1: ResponseFormat + Deserialize**
-
-Specify the SO type schema via the `ChatClientAgent{Run}Options.ChatOptions.ResponseFormat` property at agent creation or invocation time, then use `JsonSerializer.Deserialize<T>` to extract the structured data from the response text.
-
-	```csharp
-	// SO type can be provided at agent creation time
-	ChatClientAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
-	{
-		Name = "...",
-		ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() }
-	});
-
-	AgentResponse response = await agent.RunAsync("...");
-
-	PersonInfo personInfo = response.Deserialize<PersonInfo>(JsonSerializerOptions.Web);
-
-	Console.WriteLine($"Name: {personInfo.Name}");
-	Console.WriteLine($"Age: {personInfo.Age}");
-	Console.WriteLine($"Occupation: {personInfo.Occupation}");
-
-	// Alternatively, SO type can be provided at agent invocation time
-	response = await agent.RunAsync("...", new ChatClientAgentRunOptions()
-	{
-		ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() }
-	});
-
-	personInfo = response.Deserialize<PersonInfo>(JsonSerializerOptions.Web);
-
-	Console.WriteLine($"Name: {personInfo.Name}");
-	Console.WriteLine($"Age: {personInfo.Age}");
-	Console.WriteLine($"Occupation: {personInfo.Occupation}");
-	```
-
-**Approach 2: Generic RunAsync<T>**
-
-Supply the SO type as a generic parameter to `RunAsync<T>` and access the parsed result directly via the `Result` property.
-
-	```csharp
-	ChatClientAgent agent = ...;
-	
-	AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("...");
-
-	Console.WriteLine($"Name: {response.Result.Name}");
-	Console.WriteLine($"Age: {response.Result.Age}");
-	Console.WriteLine($"Occupation: {response.Result.Occupation}");
-	```
-	Note: `RunAsync<T>` is an instance method of `ChatClientAgent` and not part of the `AIAgent` base class since not all agents support structured output.
-
-Approach 1 is perceived as cumbersome by the community, as it requires additional effort when using primitive or collection types - the SO schema may need to be wrapped in an artificial JSON object. Otherwise, the caller will encounter an error like _Invalid schema for response_format 'Movie': schema must be a JSON Schema of 'type: "object"', got 'type: "array"'_. 
-This occurs because OpenAI and compatible APIs require a JSON object as the root schema.
-
-Approach 1 is also necessary in scenarios where (a) agents can only be configured with SO at creation time (such as with `AIProjectClient`), (b) the SO type is not known at compile time, or (c) the JSON schema is represented as text (for declarative agents) or as a `JsonElement`.
-
-Approach 2 is more convenient and works seamlessly with primitives and collections. However, it requires the SO type to be known at compile time, making it less flexible.
-
-Additionally, since the `RunAsync<T>` methods are instance methods of `ChatClientAgent` and are not part of the `AIAgent` base class, applying decorators like `OpenTelemetryAgent` on top of `ChatClientAgent` prevents users from accessing `RunAsync<T>`, meaning structured output is not available with decorated agents.
-
-Given the different scenarios above in which structured output can be used, there is no one-size-fits-all solution. Each approach has its own advantages and limitations,
-and the two can complement each other to provide a comprehensive structured output experience across various use cases.
-
-## Approaches Overview
-
-1. SO usage via `ResponseFormat` property
-2. SO usage via `RunAsync<T>` generic method
-
-## 1. SO usage via `ResponseFormat` property
-
-This approach should be used in the following scenarios:
- - 1.1 SO result as text is sufficient as is, and deserialization is not required
- - 1.2 SO for inter-agent collaboration
- - 1.3 SO can only be configured at agent creation time (such as with `AIProjectClient`)
- - 1.4 SO type is not known at compile time and represented by System.Type
- - 1.5 SO is represented by JSON schema and there's no corresponding .NET type either at compile time or at runtime
- - 1.6 SO in streaming scenarios, where the SO response is produced in parts
-
-**Note: Primitives and arrays are not supported by this approach.**
-
-When a caller provides a schema via `ResponseFormat`, they are explicitly telling the framework what schema to use. The framework passes that schema through as-is and
-is not responsible for transforming it. Because the framework does not own the schema, it cannot wrap primitives or arrays into a JSON object to satisfy API requirements,
-nor can it unwrap the response afterward - the caller controls the schema and is responsible for ensuring it is compatible with the underlying API.
-
-This is in contrast to the `RunAsync<T>` approach (section 2), where the caller provides a type `T` and says "make it work." In that case, the caller does not
-dictate the schema - the framework infers the schema from `T`, owns the end-to-end pipeline (schema generation, API invocation, and deserialization), and can
-therefore wrap and unwrap primitives and arrays transparently.
-
-Additionally, in streaming scenarios (1.6), the framework cannot reliably unwrap a response it did not wrap, since it has no way of knowing whether the caller wrapped the schema.Wrapping and unwrapping can only be done safely when the framework owns the entire lifecycle - from schema creation through deserialization — which is only the case with `RunAsync<T>`.
-
-If a caller needs to work with primitives or arrays via the `ResponseFormat` approach, they can easily create a wrapper type around them:
-
-```csharp
-public class MovieListWrapper
-{
-    public List<string> Movies { get; set; }
-}
-```
-
-### 1.1 SO result as text is sufficient as is, and deserialization is not required
-
-In this scenario, the caller only needs the raw JSON text returned by the model and does not need to deserialize it into a .NET type.
-The SO schema is specified via `ResponseFormat` at agent creation or invocation time, and the response text is consumed directly from the `AgentResponse`.
-
-```csharp
-AIAgent agent = chatClient.AsAIAgent();
-
-AgentRunOptions runOptions = new()
-{
-        ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>()
-};
-
-AgentResponse response = await agent.RunAsync("...", options: runOptions);
-
-Console.WriteLine(response.Text);
-```
-
-### 1.2 SO for inter-agent collaboration
-
-This scenario assumes a multi-agent setup where agents collaborate by passing messages to each other.
-One agent produces structured output as text that is then passed directly as input to the next agent, without intermediate deserialization.
-
-```csharp
-// First agent extracts structured data from unstructured input
-AIAgent extractionAgent = chatClient.AsAIAgent(new ChatClientAgentOptions()
-{
-    Name = "ExtractionAgent",
-    ChatOptions = new() 
-    { 
-        Instructions = "Extract person information from the provided text.",
-        ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() 
-    }
-});
-
-AgentResponse extractionResponse = await extractionAgent.RunAsync("John Smith is a 35-year-old software engineer.");
-
-// Pass the message with structured output text directly to the next agent
-ChatMessage soMessage = extractionResponse.Messages.Last();
-
-AIAgent summaryAgent = chatClient.AsAIAgent(new ChatClientAgentOptions()
-{
-    Name = "SummaryAgent",
-    ChatOptions = new() { Instructions = "Given the following structured person data, write a short professional bio." }
-});
-
-AgentResponse summaryResponse = await summaryAgent.RunAsync(soMessage);
-
-Console.WriteLine(summaryResponse);
-```
-
-### 1.3 SO configured at agent creation time
-
-In this scenario, the SO schema can only be configured at agent creation time (such as with `AIProjectClient`) and cannot be changed on a per-run basis.
-The caller specifies the `ResponseFormat` when creating the agent, and all subsequent invocations use the same schema.
-
-```csharp
-AIProjectClient client = ...;
-
-AIAgent agent = await client.CreateAIAgentAsync(model: "<model>", new ChatClientAgentOptions()
-{
-    Name = "...",
-    ChatOptions = new() { ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>() }
-});
-
-AgentResponse response = await agent.RunAsync("Please provide information about John Smith.");
-
-PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>(response.Text, JsonSerializerOptions.Web)!;
-
-Console.WriteLine($"Name: {personInfo.Name}");
-Console.WriteLine($"Age: {personInfo.Age}");
-Console.WriteLine($"Occupation: {personInfo.Occupation}");
-```
-
-### 1.4 SO type not known at compile time and represented by System.Type
-
-In this scenario, the SO type is not known at compile time and is provided as a `System.Type` at runtime. This is useful for dynamic scenarios where the schema is determined programmatically, 
-such as when building tooling or frameworks that work with user-defined types.
-
-```csharp
-Type soType = GetStructuredOutputTypeFromConfiguration(); // e.g., typeof(PersonInfo)
-
-ChatResponseFormat responseFormat = ChatResponseFormat.ForJsonSchema(soType);
-
-AgentResponse response = await agent.RunAsync("...", new ChatClientAgentRunOptions()
-{
-    ChatOptions = new() { ResponseFormat = responseFormat }
-});
-
-PersonInfo personInfo = (PersonInfo)JsonSerializer.Deserialize(response.Text, soType, JsonSerializerOptions.Web)!;
-```
-
-### 1.5 SO represented by JSON schema with no corresponding .NET type
-
-In this scenario, the SO schema is represented as raw JSON schema text or a `JsonElement`, and there is no corresponding .NET type available at compile time or runtime.
-This is typical for declarative agents or scenarios where schemas are loaded from external configuration.
-
-```csharp
-// JSON schema provided as a string, e.g., loaded from a configuration file
-string jsonSchema = """
-{
-    "type": "object",
-    "properties": {
-        "name": { "type": "string" },
-        "age": { "type": "integer" },
-        "occupation": { "type": "string" }
-    },
-    "required": ["name", "age", "occupation"]
-}
-""";
-
-ChatResponseFormat responseFormat = ChatResponseFormat.ForJsonSchema(
-    jsonSchemaName: "PersonInfo",
-    jsonSchema: BinaryData.FromString(jsonSchema));
-
-AgentResponse response = await agent.RunAsync("...", new ChatClientAgentRunOptions()
-{
-    ChatOptions = new() { ResponseFormat = responseFormat }
-});
-
-// Consume the SO result as text since there's no .NET type to deserialize into
-Console.WriteLine(response.Text);
-```
-
-### 1.6 SO in streaming scenarios
-
-In this scenario, the SO response is produced incrementally in parts via streaming. The caller specifies the `ResponseFormat` and consumes the response chunks as they arrive.
-Deserialization is performed after all chunks have been received.
-
-```csharp
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
-{
-    Name = "HelpfulAssistant",
-    ChatOptions = new()
-    {
-        Instructions = "You are a helpful assistant.",
-        ResponseFormat = ChatResponseFormat.ForJsonSchema<PersonInfo>()
-    }
-});
-
-IAsyncEnumerable<AgentResponseUpdate> updates = agent.RunStreamingAsync("Please provide information about John Smith, who is a 35-year-old software engineer.");
-
-AgentResponse response = await updates.ToAgentResponseAsync();
-
-// Deserialize the complete SO result after streaming is finished
-PersonInfo personInfo = JsonSerializer.Deserialize<PersonInfo>(response.Text)!;
-```
-
-## 2. SO usage via `RunAsync<T>` generic method
-
-This approach provides a convenient way to work with structured output on a per-run basis when the target type is known at compile time and a typed instance of the result
-is required.
-
-### Decision Drivers
-
-1. Support arrays and primitives as SO types
-2. Support complex types as SO types
-3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
-4. Enable SO for all AI agents, regardless of whether they natively support it
-
-### Considered Options
-
-1. `RunAsync<T>` as an instance method of `AIAgent` class delegating to virtual `RunCoreAsync<T>`
-2. `RunAsync<T>` as an extension method using feature collection
-3. `RunAsync<T>` as a method of the new `ITypedAIAgent` interface
-4. `RunAsync<T>` as an instance method of `AIAgent` class working via the new `AgentRunOptions.ResponseFormat` property
-
-### 1. `RunAsync<T>` as an instance method of `AIAgent` class delegating to virtual `RunCoreAsync<T>`
-
-This option adds the `RunAsync<T>` method directly to the `AIAgent` base class.
-
-```csharp
-public abstract class AIAgent
-{
-	public Task<AgentResponse<T>> RunAsync<T>(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        JsonSerializerOptions? serializerOptions = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default)
-		=> this.RunCoreAsync<T>(messages, session, serializerOptions, options, cancellationToken);
-
-    protected virtual Task<AgentResponse<T>> RunCoreAsync<T>(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        JsonSerializerOptions? serializerOptions = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-        throw new NotSupportedException($"The agent of type '{this.GetType().FullName}' does not support typed responses.");
-    }
-}
-```
-
-Agents with native SO support override the `RunCoreAsync<T>` method to provide their implementation. If not overridden, the method throws a `NotSupportedException`.
-
-Users will call the generic `RunAsync<T>` method directly on the agent:
-
-```csharp
-AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
-
-AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
-```
-
-Decision drivers satisfied:
-1. Support arrays and primitives as SO types
-2. Support complex types as SO types
-3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
-4. Enable SO for all AI agents, regardless of whether they natively support it
-
-Pros:
-- The `AIAgent.RunAsync<T>` method is easily discoverable.
-- Both the SO decorator and `ChatClientAgent` have compile-time access to the type `T`, allowing them to use the native `IChatClient.GetResponseAsync<T>` API, which handles primitives and collections seamlessly.
-
-Cons:
-- Agents without native SO support will still expose `RunAsync<T>`, which may be misleading.
-- `ChatClientAgent` exposing `RunAsync<T>` may be misleading when the underlying chat client does not support SO.
-- All `AIAgent` decorators must override `RunCoreAsync<T>` to properly handle `RunAsync<T>` calls.
-
-### 2. `RunAsync<T>` as an extension method using feature collection
-
-This option uses the Agent Framework feature collection (implemented via `AgentRunOptions.AdditionalProperties`) to pass a `StructuredOutputFeature` to agents, signaling that SO is requested.
-
-Agents with native SO support check for this feature. If present, they read the target type, build the schema, invoke the underlying API, and store the response back in the feature.
-```csharp
-public class StructuredOutputFeature
-{
-    public StructuredOutputFeature(Type outputType)
-    {
-        this.OutputType = outputType;
-    }
-
-    [JsonIgnore]
-    public Type OutputType { get; set; }
-
-    public JsonSerializerOptions? SerializerOptions { get; set; }
-
-    public AgentResponse? Response { get; set; }
-}
-```
-
-The `RunAsync<T>` extension method for `AIAgent` adds this feature to the collection.
-```csharp
-public static async Task<AgentResponse<T>> RunAsync<T>(
-    this AIAgent agent,
-    IEnumerable<ChatMessage> messages,
-    AgentSession? session = null,
-    JsonSerializerOptions? serializerOptions = null,
-    AgentRunOptions? options = null,
-    CancellationToken cancellationToken = default)
-{
-    // Create the structured output feature.
-    StructuredOutputFeature structuredOutputFeature = new(typeof(T))
-    {
-        SerializerOptions = serializerOptions,
-    };
-
-    // Register it in the feature collection.
-    ((options ??= new AgentRunOptions()).AdditionalProperties ??= []).Add(typeof(StructuredOutputFeature).FullName!, structuredOutputFeature);
-
-    var response = await agent.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
-
-    if (structuredOutputFeature.Response is not null)
-    {
-        return new StructuredOutputResponse<T>(structuredOutputFeature.Response, response, serializerOptions);
-    }
-
-    throw new InvalidOperationException("No structured output response was generated by the agent.");
-}
-```
-
-Users will call the `RunAsync<T>` extension method directly on the agent:
-
-```csharp
-AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
-
-AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
-```
-
-Decision drivers satisfied:
-1. Support arrays and primitives as SO types
-2. Support complex types as SO types
-3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
-4. Enable SO for all AI agents, regardless of whether they natively support it
-
-Pros:
-- The `RunAsync<T>` extension method is easily discoverable.
-- The `AIAgent` public API surface remains unchanged.
-- No changes required to `AIAgent` decorators.
-
-Cons:
-- Agents without native SO support will still expose `RunAsync<T>`, which may be misleading.
-- `ChatClientAgent` exposing `RunAsync<T>` may be misleading when the underlying chat client does not support SO.
-
-### 3. `RunAsync<T>` as a method of the new `ITypedAIAgent` interface
-
-This option defines a new `ITypedAIAgent` interface that agents with SO support implement. Agents without SO support do not implement it, allowing users to check for SO capability via interface detection.
-
-The interface:
-```csharp
-public interface ITypedAIAgent
-{
-    Task<AgentResponse<T>> RunAsync<T>(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        JsonSerializerOptions? serializerOptions = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default);
-
-    ...
-}
-```
-
-Agents with SO support implement this interface:
-```csharp
-public sealed partial class ChatClientAgent : AIAgent, ITypedAIAgent
-{
-    public async Task<AgentResponse<T>> RunAsync<T>(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        JsonSerializerOptions? serializerOptions = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-        ...
-    }
-}
-```
-
-However, `ChatClientAgent` presents a challenge: it can work with chat clients that either support or do not support SO. Implementing the interface does not guarantee 
-the underlying chat client supports SO, which undermines the core idea of using interface detection to determine SO capability.
-
-Additionally, to allow users to access interface methods on decorated agents, all decorators must implement `ITypedAIAgent`. This makes it difficult for users to 
-determine whether the underlying agent actually supports SO, further weakening the purpose of this approach.
-
-Furthermore, users would have to probe the agent type to check if it implements the `ITypedAIAgent` interface and cast it accordingly to access the `RunAsync<T>` methods.
-This adds friction to the user experience. A `RunAsync<T>` extension method for `AIAgent` could be provided to alleviate that.
-
-Given these drawbacks, this option is more complex to implement than the others without providing clear benefits.
-
-Decision drivers satisfied:
-1. Support arrays and primitives as SO types
-2. Support complex types as SO types
-3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
-4. Enable SO for all AI agents, regardless of whether they natively support it
-
-Pros:
-- Both the SO decorator and `ChatClientAgent` have compile-time access to the type `T`, allowing them to use the native `IChatClient.GetResponseAsync<T>` API, which handles primitives and collections seamlessly.
-
-Cons:
-- `ChatClientAgent` implementing `ITypedAIAgent` may be misleading when the underlying chat client does not support SO.
-- All `AIAgent` decorators must implement `ITypedAIAgent` to handle `RunAsync<T>` calls.
-- Decorators implementing the interface may mislead users into thinking the underlying agent natively supports SO.
-- Agents must implement all members of `ITypedAIAgent`, not just a core method.
-- Users must check the agent type and cast to `ITypedAIAgent` to access `RunAsync<T>`.
-
-### 4. `RunAsync<T>` as an instance method of `AIAgent` class working via the new `AgentRunOptions.ResponseFormat` property
-
-This option adds a `ResponseFormat` property of type `ChatResponseFormat` to `AgentRunOptions`. Agents that support SO check for the presence of 
-this property in the options passed to `RunAsync` to determine whether structured output is requested. If present, they use the schema from `ResponseFormat` 
-to invoke the underlying API and obtain the SO response.
-
-```csharp
-public class AgentRunOptions
-{
-    public ChatResponseFormat? ResponseFormat { get; set; }
-}
-```
-
-Additionally, a generic `RunAsync<T>` method is added to `AIAgent` that initializes the `ResponseFormat` based on the type `T` and delegates to the non-generic `RunAsync`.
-
-```csharp
-public abstract class AIAgent
-{
-	public async Task<AgentResponse<T>> RunAsync<T>(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        JsonSerializerOptions? serializerOptions = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-        serializerOptions ??= AgentAbstractionsJsonUtilities.DefaultOptions;
-
-        var responseFormat = ChatResponseFormat.ForJsonSchema<T>(serializerOptions);
-
-        options = options?.Clone() ?? new AgentRunOptions();
-        options.ResponseFormat = responseFormat;
-
-        AgentResponse response = await this.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
-
-        return new AgentResponse<T>(response, serializerOptions);
-    }
-}
-```
-
-Users call the generic `RunAsync<T>` method directly on the agent:
-
-```csharp
-AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
-
-AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
-```
-
-Decision drivers satisfied:
-1. Support arrays and primitives as SO types
-2. Support complex types as SO types
-3. Work with `AIAgent` decorators (e.g., `OpenTelemetryAgent`)
-4. Enable SO for all AI agents, regardless of whether they natively support it
-
-Pros:
-- The `AIAgent.RunAsync<T>` method is easily discoverable.
-- No changes required to `AIAgent` decorators
-
-Cons:
-- Agents without native SO support will still expose `RunAsync<T>`, which may be misleading.
-- `ChatClientAgent` exposing `RunAsync<T>` may be misleading when the underlying chat client does not support SO.
-
-### Decision Table
-
-|  | Option 1: Instance method + RunCoreAsync<T> | Option 2: Extension method + feature collection | Option 3: ITypedAIAgent Interface | Option 4: Instance method + AgentRunOptions.ResponseFormat |
-|---|---|---|---|---|
-| Discoverability | ✅ `RunAsync<T>` easily discoverable | ✅ `RunAsync<T>` easily discoverable | ❌ Requires type check and cast | ✅ `RunAsync<T>` easily discoverable |
-| Decorator changes | ❌ All decorators must override `RunCoreAsync<T>` | ✅ No changes required | ❌ All decorators must implement `ITypedAIAgent` | ✅ No changes required to decorators |
-| Primitives/collections handling | ✅ Native support via `IChatClient.GetResponseAsync<T>` | ❌ Must wrap/unwrap internally | ✅ Native support via `IChatClient.GetResponseAsync<T>` | ❌ Must wrap/unwrap internally |
-| Misleading API exposure | ❌ Agents without SO still expose `RunAsync<T>` | ❌ Agents without SO still expose `RunAsync<T>` | ❌ Interface on `ChatClientAgent` may be misleading | ❌ Agents without SO still expose `RunAsync<T>` |
-| Implementation burden | ❌ Decorators must override method | ❌ Must handle schema wrapping | ❌ Agents must implement all interface members | ✅ Delegates to existing `RunAsync` via `ResponseFormat` |
-
-## Cross-Cutting Aspects
-
-1. **The `useJsonSchemaResponseFormat` parameter**: The `ChatClientAgent.RunAsync<T>` method has this parameter to enable structured output on LLMs that do not natively support it.
-  It works by adding a user message like "Respond with a JSON value conforming to the following schema:" along with the JSON schema. However, this approach has not been reliable historically. The recommendation is not to carry this parameter forward, regardless of which option is chosen.
-
-2. **Primitives and array types handling**: There are a few options for how primitive and array types can be handled in the Agent Framework:
-
-   1. **Never wrap**, regardless of whether the schema is provided via `ResponseFormat` or `RunAsync<T>`.
-       - Pro: No changes needed; user has full control.
-       - Pro: No issues with unwrapping in streaming scenarios.
-       - Con: User must wrap manually.
-
-   2. **Always wrap**, regardless of whether the schema is provided via `ResponseFormat` or `RunAsync<T>`.
-       - Pro: Consistent wrapping behavior; no manual wrapping needed.
-       - Con: Inconsistent unwrapping behavior; it may be unexpected to have SO result wrapped when schema is provided via `ResponseFormat`.
-       - Con: Impossible to know if SO result is wrapped to unwrap it in streaming scenarios.
-
-   3. **Wrap only for `RunAsync<T>`** and do not wrap the schema provided via `ResponseFormat`.
-       - Pro: No unexpectedly wrapped result when schema is provided via `ResponseFormat`.
-       - Pro: Solves the problem with unwrapping in streaming scenarios.
-
-   4. **User decides** whether to wrap schema provided via `ResponseFormat` using a new `wrapPrimitivesAndArrays` property of `ChatResponseFormatJson`. For SO provided via `RunAsync<T>`, AF always wraps.
-       - Pro: No manual wrapping needed; just flip a switch.
-       - Pro: Solves the problem with unwrapping in streaming scenarios.
-       - Con: Extends the public API surface.
-
-3. **Structured output for agents without native SO support**: Some AI agents in AF do not support structured output natively. This is either because it is not part of the protocol (e.g., A2A agent) or because the agents use LLMs without structured output capabilities.
-   To address this gap, AF can provide the `StructuredOutputAgent` decorator. This decorator wraps any `AIAgent` and adds structured output support by obtaining the text response from the decorated agent and delegating it to a configured chat client for JSON transformation.
-   
-   ```csharp
-   public class StructuredOutputAgent : DelegatingAIAgent
-   {
-        private readonly IChatClient _chatClient;
-
-        public StructuredOutputAgent(AIAgent innerAgent, IChatClient chatClient)
-            : base(innerAgent)
-        {
-            this._chatClient = Throw.IfNull(chatClient);
-        }
-
-        protected override async Task<AgentResponse<T>> RunCoreAsync<T>(
-            IEnumerable<ChatMessage> messages,
-            AgentSession? session = null,
-            JsonSerializerOptions? serializerOptions = null,
-            AgentRunOptions? options = null,
-            CancellationToken cancellationToken = default)
-        {
-            // Run the inner agent first, to get back the text response we want to convert.
-            var textResponse = await this.InnerAgent.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
-
-            // Invoke the chat client to transform the text output into structured data.
-            ChatResponse<T> soResponse = await this._chatClient.GetResponseAsync<T>(
-                messages:
-                [
-                    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, textResponse.Text)
-                ],
-                serializerOptions: serializerOptions ?? AgentJsonUtilities.DefaultOptions,
-                cancellationToken: cancellationToken).ConfigureAwait(false);
-
-            return new StructuredOutputAgentResponse(soResponse, textResponse);
-        }
-   }
-   ```
-
-   The decorator preserves the original response from the decorated agent and surfaces it via the `OriginalResponse` property on the returned `StructuredOutputAgentResponse`.
-   This allows users to access both the original unstructured response and the new structured response when using this decorator.
-   ```csharp
-   public class StructuredOutputAgentResponse : AgentResponse
-   {
-       internal StructuredOutputAgentResponse(ChatResponse chatResponse, AgentResponse agentResponse) : base(chatResponse)
-       {
-           this.OriginalResponse = agentResponse;
-       }
-       
-       public AgentResponse OriginalResponse { get; }
-    }
-   ```
-   
-   The decorator can be registered during the agent configuration step using the `UseStructuredOutput` extension method on `AIAgentBuilder`.
-
-   ```csharp
-   IChatClient meaiChatClient = chatClient.AsIChatClient();
-
-   AIAgent baseAgent = meaiChatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
-
-   // Register the StructuredOutputAgent decorator during agent building
-   AIAgent agent = baseAgent
-       .AsBuilder()
-       .UseStructuredOutput(meaiChatClient)
-       .Build();
-
-   AgentResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
-
-   Console.WriteLine($"Name: {response.Result.Name}");
-   Console.WriteLine($"Age: {response.Result.Age}");
-   Console.WriteLine($"Occupation: {response.Result.Occupation}");
-   
-   var originalResponse = ((StructuredOutputAgentResponse)response.RawRepresentation!).OriginalResponse;
-   Console.WriteLine($"Original unstructured response: {originalResponse.Text}");
-
-   ```
-
-## Decision Outcome
-
-It was decided to keep both approaches for structured output - via `ResponseFormat` and via `RunAsync<T>` since they serve different scenarios and use cases.
-
-For the `RunAsync<T>` approach, option 4 was selected, which adds a generic `RunAsync<T>` method to `AIAgent` that works via the new `AgentRunOptions.ResponseFormat` property.
-This was chosen for its simplicity and because no changes are required to existing `AIAgent` decorators.
-
-For cross-cutting aspects, the `useJsonSchemaResponseFormat` parameter will not be carried forward due to reliability issues.
-
-For handling primitives and array types, option 3 was selected: wrap only for `RunAsync<T>` and do not wrap the schema provided via `ResponseFormat`.
-This avoids the issues described in the Approach 1 section note.
-
-Finally, it was decided not to include the `StructuredOutputAgent` decorator in the framework, since the reliability of producing structured output via an additional
-LLM call may not be sufficient for all scenarios. Instead, this pattern is provided as a sample to demonstrate how structured output can be achieved for agents without native support,
-giving users a reference implementation they can adapt to their own requirements.

docs/decisions/0017-agent-additional-properties.md

@@ -1,211 +0,0 @@
----
-status: accepted
-contact: westey-m
-date: 2026-02-24
-deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub, lokitoth, alliscode, taochenosu, moonbox3
-consulted:
-informed:
----
-
-# AdditionalProperties for AIAgent and AgentSession
-
-## Context and Problem Statement
-
-The `AIAgent` base class currently exposes `Id`, `Name`, and `Description` as its core metadata properties, and `AgentSession` exposes only a `StateBag` property.
-Neither type has a mechanism for attaching arbitrary metadata, such as protocol-specific descriptors (e.g., A2A agent cards), hosting attributes, session-level tags, or custom user-defined metadata for discovery and routing.
-
-Other types in the framework already carry `AdditionalProperties` — notably `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate` — all using `AdditionalPropertiesDictionary` from `Microsoft.Extensions.AI`.
-Adding a similar property to `AIAgent` and `AgentSession` would give both types a consistent, extensible metadata surface.
-
-Related: [Work Item #2133](https://github.com/microsoft/agent-framework/issues/2133)
-
-## Decision Drivers
-
-- **Consistency**: Other core types (`AgentRunOptions`, `AgentResponse`, `AgentResponseUpdate`) already expose `AdditionalProperties`. `AIAgent` and `AgentSession` are the major abstractions that lack this.
-- **Extensibility**: Hosting libraries, protocol adapters (A2A, AG-UI), and discovery mechanisms need a place to attach agent-level and session-level metadata without subclassing.
-- **Simplicity**: The solution should be easy to understand and use; avoid over-engineering.
-- **Minimal breaking change**: The addition should not require changes to existing agent implementations.
-- **Clear semantics**: Users should understand what `AdditionalProperties` on an agent or session means and how it differs from `AdditionalProperties` on `AgentRunOptions`.
-
-## Considered Options
-
-### Surface Area
-
-- **Option A**: Public get-only property, auto-initialized (`AdditionalPropertiesDictionary AdditionalProperties { get; } = new()`) on both `AIAgent` and `AgentSession`
-- **Option B**: Public get/set nullable property (`AdditionalPropertiesDictionary? AdditionalProperties { get; set; }`) on both `AIAgent` and `AgentSession`
-- **Option C**: Constructor-injected dictionary with public get-only accessor on both `AIAgent` and `AgentSession`
-- **Option D**: External container/wrapper object — metadata lives outside `AIAgent` and `AgentSession`; no changes to the base classes
-
-### Semantics
-
-- **Option 1**: Metadata only — describes the agent or session; not propagated when calling `IChatClient`
-- **Option 2**: Passed down the stack — merged into `ChatOptions.AdditionalProperties` during `ChatClientAgent` runs
-
-## Decision Outcome
-
-The chosen option is **Option D + Option 1**: an external container/wrapper object, used purely as metadata.
-
-### Consequences
-
-- Good, because `AIAgent` and `AgentSession` remain unchanged, avoiding any increase to the core framework surface area while still enabling extensible metadata.
-- Good, because an external wrapper (owned by hosting/protocol libraries or user code, not the `AIAgent` / `AgentSession` base classes) can internally use `AdditionalPropertiesDictionary` to stay consistent with existing patterns on `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate`.
-- Good, because metadata-only semantics keep a clean separation from per-run extensibility (`AgentRunOptions.AdditionalProperties`) and avoid unexpected side effects during agent execution.
-- Good, because no additional allocation occurs on `AIAgent` or `AgentSession` when no metadata is needed; external wrappers can be created only when metadata is required.
-- Bad, because callers and libraries must manage and pass around both the agent/session instance and its associated metadata wrapper, keeping them correctly associated.
-- Bad, because different hosting or protocol layers may define their own wrapper types, which can fragment the ecosystem unless conventions are agreed upon.
-
-## Pros and Cons of the Options
-
-### Option A — Public get-only property, auto-initialized
-
-The property is always non-null and ready to use. Users add metadata after construction.
-
-```csharp
-public abstract partial class AIAgent
-{
-    public AdditionalPropertiesDictionary AdditionalProperties { get; } = new();
-}
-
-public abstract partial class AgentSession
-{
-    public AdditionalPropertiesDictionary AdditionalProperties { get; } = new();
-}
-
-// Usage
-agent.AdditionalProperties["protocol"] = "A2A";
-agent.AdditionalProperties.Add<MyAgentCardInfo>(cardInfo);
-session.AdditionalProperties["tenant"] = tenantId;
-```
-
-- Good, because users never encounter `null` — no defensive null checks needed.
-- Good, because the dictionary reference cannot be replaced, preventing accidental data loss.
-- Good, because it is the simplest API surface to use.
-- Neutral, because it always allocates, even when no metadata is needed. The allocation cost is negligible.
-- Bad, because it cannot be set at construction time as a single object (users must populate it post-construction).
-
-### Option B — Public get/set nullable property
-
-Matches the existing pattern on `AgentRunOptions`, `AgentResponse`, and `AgentResponseUpdate`.
-
-```csharp
-public abstract partial class AIAgent
-{
-    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
-}
-
-public abstract partial class AgentSession
-{
-    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
-}
-
-// Usage
-agent.AdditionalProperties ??= new();
-agent.AdditionalProperties["protocol"] = "A2A";
-session.AdditionalProperties ??= new();
-session.AdditionalProperties["tenant"] = tenantId;
-```
-
-- Good, because it is consistent with the existing `AdditionalProperties` pattern on `AgentRunOptions` and `AgentResponse`.
-- Good, because it avoids allocation when no metadata is needed.
-- Bad, because every consumer must null-check before reading or writing.
-- Bad, because the entire dictionary can be replaced, risking accidental loss of metadata set by other components (e.g., a hosting library sets metadata, then user code replaces the dictionary).
-
-### Option C — Constructor-injected with public get
-
-The dictionary is provided at construction time and exposed as get-only.
-
-```csharp
-public abstract partial class AIAgent
-{
-    public AdditionalPropertiesDictionary AdditionalProperties { get; }
-
-    protected AIAgent(AdditionalPropertiesDictionary? additionalProperties = null)
-    {
-        this.AdditionalProperties = additionalProperties ?? new();
-    }
-}
-
-public abstract partial class AgentSession
-{
-    public AdditionalPropertiesDictionary AdditionalProperties { get; }
-
-    protected AgentSession(AdditionalPropertiesDictionary? additionalProperties = null)
-    {
-        this.AdditionalProperties = additionalProperties ?? new();
-    }
-}
-```
-
-- Good, because an agent's metadata can be established before any code runs against it.
-- Bad, because `AdditionalPropertiesDictionary` has no read-only variant, so the constructor-injection pattern gives a false sense of immutability — callers can still mutate the dictionary contents after construction.
-- Bad, because it requires adding a constructor parameter to the abstract base classes, which is a source-breaking change for all existing `AIAgent` and `AgentSession` subclasses (even with a default value, it changes the constructor signature that derived classes chain to).
-- Bad, because it is more complex with little practical benefit over Option A, since post-construction mutation is equally possible.
-
-### Option D — External container/wrapper object
-
-Rather than adding `AdditionalProperties` to `AIAgent` or `AgentSession`, users wrap the agent or session in a container object that carries both the instance and any associated metadata. No changes to the base classes are required.
-
-```csharp
-public class AgentWithMetadata
-{
-    public required AIAgent Agent { get; init; }
-    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
-}
-
-public class SessionWithMetadata
-{
-    public required AgentSession Session { get; init; }
-    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
-}
-
-// Usage
-var wrapper = new AgentWithMetadata
-{
-    Agent = myAgent,
-    AdditionalProperties = new() { ["protocol"] = "A2A" }
-};
-```
-
-- Good, because it requires no changes to `AIAgent` or `AgentSession`, avoiding any risk of breaking existing implementations.
-- Good, because metadata is clearly external to the agent and session, eliminating any ambiguity about whether it might be passed down the execution stack.
-- Good, because the container pattern gives the user full control over the metadata lifecycle and serialization.
-- Bad, because it is not discoverable — users must know about the container convention; there is no built-in API surface guiding them.
-
-### Option 1 — Metadata only
-
-`AdditionalProperties` on `AIAgent` and `AgentSession` is descriptive metadata. It is **not** automatically propagated when the agent calls downstream services such as `IChatClient`.
-
-- Good, because it keeps a clean separation of concerns: agent/session-level metadata vs. per-run options.
-- Good, because it avoids unintended side effects — metadata added for discovery or hosting won't leak into LLM requests.
-- Good, because per-run extensibility is already served by `AgentRunOptions.AdditionalProperties` (see [ADR 0014](0014-feature-collections.md)), so there is no gap.
-- Neutral, because users who want to pass agent metadata to the chat client can still do so manually via `AgentRunOptions`.
-
-### Option 2 — Passed down the stack
-
-`AdditionalProperties` on `AIAgent` and `AgentSession` are automatically merged into `ChatOptions.AdditionalProperties` (or similar) when `ChatClientAgent` invokes the underlying `IChatClient`.
-
-- Good, because it provides an automatic way to send agent-level configuration to the LLM provider.
-- Bad, because it conflates metadata (describing the agent) with operational parameters (controlling LLM behavior), leading to potential confusion.
-- Bad, because it risks leaking unrelated metadata into LLM calls (e.g., hosting tags, discovery URLs).
-- Bad, because it would be `ChatClientAgent`-specific behavior on a base-class property, creating inconsistency for non-`ChatClientAgent` implementations.
-- Bad, because it duplicates the purpose of `AgentRunOptions.AdditionalProperties`, which already serves as the per-run extensibility point for passing data down the stack.
-
-## Serialization Considerations
-
-`AIAgent` instances are not typically serialized, so `AdditionalProperties` on `AIAgent` does not raise serialization concerns.
-
-`AgentSession` instances, however, are routinely serialized and deserialized — for example, to persist conversation state across application restarts. Adding `AdditionalProperties` to `AgentSession` introduces a serialization challenge: `AdditionalPropertiesDictionary` is a `Dictionary<string, object?>`, and `object?` values do not carry enough type information for the JSON deserializer to reconstruct the original CLR types.
-
-### Default behavior — JsonElement round-tripping
-
-By default, when an `AgentSession` with `AdditionalProperties` is serialized and later deserialized, any complex objects stored as values in the dictionary will be deserialized as `JsonElement` rather than their original types. This is the same behavior exhibited by `ChatMessage.AdditionalProperties` and other `AdditionalPropertiesDictionary` usages in `Microsoft.Extensions.AI`, and is the approach we will follow.
-
-### Custom serialization via JsonSerializerOptions
-
-`AIAgent.SerializeSessionAsync` and `AIAgent.DeserializeSessionAsync` already accept an optional `JsonSerializerOptions` parameter. Users who need strongly-typed round-tripping of `AdditionalProperties` values can supply custom options with appropriate converters or type info resolvers. This is non-trivial to implement but provides full control over deserialization behavior when needed.
-
-## More Information
-
-- [ADR 0014 — Feature Collections](0014-feature-collections.md) established that `AdditionalProperties` on `AgentRunOptions` serves as the per-run extensibility mechanism. The proposed agent-level and session-level properties serve a complementary, distinct purpose: static metadata describing the agent or session itself.
-- `AdditionalPropertiesDictionary` is defined in `Microsoft.Extensions.AI` and is already a dependency of `Microsoft.Agents.AI.Abstractions`. No new package references are needed.
-- Type-safe access is available via the existing `AdditionalPropertiesExtensions` helper methods (`Add<T>`, `TryGetValue<T>`, `Contains<T>`, `Remove<T>`), which use `typeof(T).FullName` as the dictionary key.

docs/decisions/0018-agentthread-serialization.md

@@ -1,163 +0,0 @@
----
-# These are optional elements. Feel free to remove any of them.
-status: accepted
-contact: westey-m
-date: 2026-02-25
-deciders: sergeymenshykh, markwallace, rbarreto, dmytrostruk, westey-m, eavanvalkenburg, stephentoub
-consulted: 
-informed:
----
-
-# AgentSession serialization
-
-## Context and Problem Statement
-
-Serializing AgentSessions is done today by calling SerializeSession on the AIAgent instance and deserialization
-is done via the DeserializeSession method on the AIAgent instance.
-
-This approach has some drawbacks:
-
-1. It requires each AgentSession implementation to implement its own serialization logic. This can lead to inconsistencies and errors if not done correctly.
-1. It means that only one serialization format can be supported at a time. If we want to support multiple formats (e.g., JSON, XML, binary), we would need to implement separate serialization logic for each format.
-1. It is not possible to serialize and deserialize lists of AgentSessions, since each need to be handled individually.
-1. Users may not realise that they need to call these specific methods to serialize/deserialize AgentSessions.
-
-The reason why this approach was chosen initially is that AgentSessions may have behaviors that are attached to them and only the agent knows what behaviors to attach.
-These behaviors also have their own state that are attached to the AgentSession.
-The behaviors may have references to SDKs or other resources that cannot be created via standard deserialization mechanisms.
-E.g. an AgentSession may have a custom ChatMessageStore that knows how to store chat history in a specific storage backend and has a reference to the SDK client for that backend.
-When deserializing the AgentSession, we need to make sure that the ChatMessageStore is created with the correct SDK client.
-
-## Decision Drivers
-
-- A. Ability to continue to support custom behaviors (AIContextProviders / ChatHistoryProviders).
-- B. Ability to serialize and deserialize AgentSessions via standard serialization mechanisms, e.g. JsonSerializer.Serialize and JsonSerializer.Deserialize.
-- C. Ability for the caller to access custom providers.
-
-## Considered Options
-
-- Option 1: Separate state from behavior, serialize state only and re-attach behavior on first usage
-- Option 2: Separate state from behavior, and only have state on AgentSession
-- Option 3: Keep the current approach of custom Serialize/Deserialize methods
-
-### Option 1: Separate state from behavior, serialize state only and re-attach behavior on first usage
-
-Decision Drivers satisfied: A, B and C (C only partially)
-
-Have separate properties on the AgentSession for state and behavior and mark the behavior property with [JsonIgnore].
-After deserializing the AgentSession, the behavior is null and when the AgentSession is first used by the Agent, the behavior is created and attached to the AgentSession.
-
-This requires polymorphic deserialization to be supported, so that the correct AgentSession subclass and the correct behavior state is created during deserialization.
-Since the implementations for AgentSessions and their behaviors are not all known at compile time, we need a way to register custom AgentSession types and their corresponding behavior types for serialization with System.Text.Json on our JsonUtilities helpers.
-
-A drawback of this approach is that the AgentSession is in an incomplete state after deserialization until it is first used,
-so if a user was to call `GetService<MyBehavior>()` on the AgentSession before it is used by the Agent, it would return null.
-
-Behaviors like ChatMessageStore and AIContextProviders would need to change to support taking state as input and exposing state publicly.
-
-```csharp
-public class ChatClientAgentSession
-{
-    ...
-    public ChatMessageStoreState ChatMessageStoreState { get; }
-    public ChatMessageStore? ChatMessageStore { get; }
-    ...
-}
-
-[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
-[JsonDerivedType(typeof(InMemoryChatMessageStoreState), nameof(InMemoryChatMessageStoreState))]
-public abstract class ChatMessageStoreState
-{
-}
-public class InMemoryChatMessageStoreState : ChatMessageStoreState
-{
-    public IList<ChatMessage> Messages { get; set; } = [];
-}
-
-public abstract class ChatMessageStore<TState>
-    where TState : ChatMessageStoreState
-{
-    ...
-    public abstract TState State { get; }
-    ...
-}
-
-public sealed class InMemoryChatMessageStore : ChatMessageStore<InMemoryChatMessageStoreState>, IList<ChatMessage>
-{
-    private readonly InMemoryChatMessageStoreState _state;
-
-    public InMemoryChatMessageStore(InMemoryChatMessageStoreState? state)
-    {
-        this._state = state ?? new InMemoryChatMessageStoreState();
-    }
-
-    public override InMemoryChatMessageStoreState State => this._state;
-
-    ...
-}
-```
-
-ChatClientAgent factories would need to change to support creating behaviors based on state:
-
-```csharp
-    public Func<ChatMessageStoreFactoryContext, ChatMessageStore>? ChatMessageStoreFactory { get; set; }
-
-    public class ChatMessageStoreFactoryContext
-    {
-        public ChatMessageStoreState? State { get; set; }
-    }
-```
-
-The run behavior of the ChatClientAgent would be as follows:
-
-1. If an AgentSession is provided, check if the ChatMessageStore property is null.
-1. If it is, check if the ChatMessageStoreState property is null.
-    1. If ChatMessageStoreState is null, check if there is a provided ChatMessageStoreFactory.
-        1. If there is, call it with a ChatMessageStoreFactoryContext containing null State to create a default ChatMessageStore behavior, and update the AgentSession with the created behavior and its state.
-        2. If there is not, create a default InMemoryChatMessageStore behavior, and update the AgentSession with the created behavior and its state.
-    1. If ChatMessageStoreState is not null, check if there is a provided ChatMessageStoreFactory.
-        1. If there is, call it with a ChatMessageStoreFactoryContext containing the State to create a ChatMessageStore behavior based on the state.
-        2. If there is not, create an InMemoryChatMessageStore behavior based on the State.
-
-### Option 2: Separate state from behavior, and only have state on AgentSession
-
-Decision Drivers satisfied: A, B and C.
-
-This is similar to Option 1 but instead of having a behavior property on the AgentSession, we only have a StateBag property on the AgentSession.
-Behaviors really make more sense to live with the agent rather than the Session, but state should live on the session.
-When the AgentSession is used by the Agent, the Agent runs the behaviors against the Session, and the behavior stores it's state on the Session StateBag.
-
-This means that users are unable to access the behavior from the AgentSession, e.g. via `AgentSession.GetService<TBehavior>()`.
-
-However, the behaviors can be public properties on the Agent or can be retrieved from the agent via `AIAgent.GetService<MyAIContextProvider>()`.
-
-```csharp
-public class AgentSession
-{
-    ...
-    public AgentSessionStateBag StateBag { get; protected set; } = new();
-    ...
-}
-```
-
-### Option 3: Keep the current approach of custom Serialize/Deserialize methods
-
-Decision Drivers satisfied: A and C
-
-This option keeps the current approach of having custom Serialize/Deserialize methods on the AgentSession and AIAgent.
-
-## Decision Outcome
-
-Chosen option:
-
-**Option 2** — separate state from behavior, with only state on the AgentSession — because it satisfies all decision drivers and provides the cleanest separation of concerns. Since not all AgentSession implementations have yet been cleanly separated from their behaviors, AIAgent.SerializeSession and AIAgent.DeserializeSession is kept for the time being, but most session types can be serialized and deserialized directly using JsonSerializer.
-
-### Consequences
-
-- Good, because providers are fully stateless — the same provider instance works correctly across any number of concurrent sessions without risk of state leakage.
-- Good, because `AgentSession` can be serialized and deserialized with standard `System.Text.Json` mechanisms, satisfying decision driver B.
-- Good, because the generic `StateBag` is extensible — new providers can store arbitrary state without requiring changes to the session class.
-- Good, because users can access providers via the agent (e.g. `agent.GetService<InMemoryChatHistoryProvider>()`) satisfying decision driver C.
-- Good, because sessions are always in a complete and valid state after deserialization — there is no "incomplete until first use" problem as in Option 1.
-- Neutral, because providers cannot be accessed directly from the session; callers must go through the agent. This is a minor usability trade-off but keeps the session focused on state only.
-- Bad, because each provider must be disciplined about using `ProviderSessionState<T>` and not storing session-specific data in instance fields. This is a correctness concern for custom provider implementers.

docs/features/durable-agents/AGENTS.md

@@ -1,48 +0,0 @@
-# AGENTS.md
-
-Instructions for AI coding agents working on durable agents documentation.
-
-## Scope
-
-This directory contains feature documentation for the durable agents integration. The source code and samples live elsewhere:
-
-- .NET implementation: `dotnet/src/Microsoft.Agents.AI.DurableTask/` and `dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions/`
-- Python implementation: `python/packages/durabletask/` and `python/packages/azurefunctions/` (package `agent-framework-azurefunctions`)
-- .NET samples: `dotnet/samples/04-hosting/DurableAgents/`
-- Python samples: `python/samples/04-hosting/durabletask/`
-- Official docs (Microsoft Learn): <https://learn.microsoft.com/agent-framework/integrations/azure-functions>
-
-## Document structure
-
-| File | Purpose |
-| --- | --- |
-| `README.md` | Main technical overview: architecture, hosting models, orchestration patterns, and links to samples. |
-| `durable-agents-ttl.md` | Deep-dive on session Time-To-Live (TTL) configuration and behavior. |
-
-Add new sibling documents when a topic is too detailed for the README (e.g., a new feature like reliable streaming or MCP tool exposure). Keep the README focused on orientation and link out to siblings for depth.
-
-## Writing guidelines
-
-- **Audience**: Developers already familiar with the Microsoft Agent Framework who want to understand what durability adds and how to use it.
-- **Host-agnostic first**: Durable agents work in console apps, Azure Functions, and any Durable Task–compatible host. Show host-agnostic patterns (plain orchestration functions, `IServiceCollection` registration) before Azure Functions–specific patterns. Avoid giving the impression that Azure Functions is the only hosting option.
-- **Both languages**: Always include C# and Python examples side by side. Keep them equivalent in functionality.
-- **Callout syntax**: Use GitHub-flavored callouts (`> [!NOTE]`, `> [!IMPORTANT]`, `> [!WARNING]`) rather than bold-text callouts (`> **Note:** ...`).
-- **Line length**: Do not wrap long lines. Rely on text viewers / renderers for line wrapping.
-- **Tables**: Use spaces around pipes in separator rows (`| --- |` not `|---|`).
-- **Code snippets**: Keep them minimal and self-contained. Omit boilerplate (using statements, environment variable reads) unless the snippet is specifically about setup.
-- **Cross-references**: Link to Microsoft Learn for conceptual background (Durable Entities, Durable Task Scheduler, Azure Functions). Link to sibling docs within this directory for feature deep-dives.
-
-## Linting
-
-Run markdownlint on all documents before committing, with line-length checks disabled:
-
-```bash
-markdownlint docs/features/durable-agents/ --disable MD013
-```
-
-## When to update these docs
-
-- A new durable agent feature is added (e.g., a new orchestration pattern, hosting model, or configuration option).
-- The public API surface changes in a way that affects how developers use durable agents.
-- New sample directories are added — update the sample links in README.md.
-- The official Microsoft Learn documentation is restructured — update external links.

docs/features/durable-agents/README.md

@@ -1,239 +0,0 @@
-# Durable agents
-
-## Overview
-
-Durable agents extend the standard Microsoft Agent Framework with **durable state management** powered by the Durable Task framework. An ordinary Agent Framework agent runs in-process: its conversation history lives in memory and is lost when the process ends. A durable agent persists conversation history and execution state in external storage so that sessions survive process restarts, failures, and scale-out events.
-
-| Capability | Ordinary agent | Durable agent |
-| --- | --- | --- |
-| Conversation history | In-memory only | Durably persisted |
-| Failure recovery | State lost on crash | Automatically resumed |
-| Multi-instance scale-out | Not supported | Any worker can resume a session |
-| Multi-agent orchestrations | Manual coordination | Deterministic, checkpointed workflows |
-| Human-in-the-loop | Must keep process alive | Can wait days/weeks with zero compute |
-| Hosting | Any process | Console app, Azure Functions, or any Durable Task–compatible host |
-
-> [!NOTE]
-> For a step-by-step tutorial and deployment guidance, see [Azure Functions (Durable)](https://learn.microsoft.com/agent-framework/integrations/azure-functions) on Microsoft Learn.
-
-## How durable agents work
-
-Durable agents are implemented on top of [Durable Entities](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-entities) (also called "virtual actors"). Each **agent session** maps to one entity instance whose state contains the full conversation history. When you send a message to a durable agent, the following happens:
-
-1. The message is dispatched to the entity identified by an `AgentSessionId` (a composite of the agent name and a unique session key).
-2. The entity loads its persisted `DurableAgentState`, which includes the complete conversation history.
-3. The entity invokes the underlying `AIAgent` with the full conversation history, collects the response, and appends both the request and the response to the state.
-4. The updated state is persisted back to durable storage automatically.
-
-Because the entity framework serializes access to each entity instance, concurrent messages to the same session are processed one at a time, eliminating race conditions.
-
-### Agent session identity
-
-Every durable agent session is identified by an `AgentSessionId`, which has two components:
-
-- **Name** – the registered name of the agent (case-insensitive).
-- **Key** – a unique session key (case-sensitive), typically a GUID.
-
-The session ID is mapped to an underlying Durable Task entity ID with a `dafx-` prefix (e.g., `dafx-joker`). This naming convention is consistent across both .NET and Python implementations.
-
-## Architecture
-
-### .NET
-
-The .NET implementation consists of two NuGet packages:
-
-| Package | Purpose |
-| --- | --- |
-| `Microsoft.Agents.AI.DurableTask` | Core durable agent types: `DurableAIAgent`, `AgentEntity`, `DurableAgentSession`, `AgentSessionId`, `DurableAgentsOptions`, and the state model. |
-| `Microsoft.Agents.AI.Hosting.AzureFunctions` | Azure Functions hosting integration: auto-generated HTTP endpoints, MCP tool triggers, entity function triggers, and the `ConfigureDurableAgents` extension method on `FunctionsApplicationBuilder`. |
-
-Key types:
-
-- **`DurableAIAgent`** – A subclass of `AIAgent` used *inside orchestrations*. Obtained via `context.GetAgent("agentName")`, it routes `RunAsync` calls through the orchestration's entity APIs so that each call is checkpointed.
-- **`DurableAIAgentProxy`** – A subclass of `AIAgent` used *outside orchestrations* (e.g., from HTTP triggers or console apps). It signals the entity via `DurableTaskClient` and polls for the response.
-- **`AgentEntity`** – The `TaskEntity<DurableAgentState>` that hosts the real agent. It loads the registered `AIAgent` by name, wraps it in an `EntityAgentWrapper`, feeds it the full conversation history, and persists the result.
-- **`DurableAgentSession`** – An `AgentSession` subclass that carries the `AgentSessionId`.
-- **`DurableAgentsOptions`** – Builder for registering agents and configuring TTL.
-
-### Python
-
-The core Python implementation is in the `agent-framework-durabletask` package (`python/packages/durabletask`). Azure Functions hosting (including `AgentFunctionApp`) is in the separate `agent-framework-azurefunctions` package (`python/packages/azurefunctions`).
-
-Key types:
-
-- **`DurableAIAgent`** – A generic proxy (`DurableAIAgent[TaskT]`) implementing `SupportsAgentRun`. Returns a `TaskT` from `run()` — either an `AgentResponse` (client context) or a `DurableAgentTask` (orchestration context, must be `yield`ed).
-- **`DurableAIAgentWorker`** – Wraps a `TaskHubGrpcWorker` and registers agents as durable entities via `add_agent()`.
-- **`DurableAIAgentClient`** – Wraps a `TaskHubGrpcClient` for external callers. `get_agent()` returns a `DurableAIAgent[AgentResponse]`.
-- **`DurableAIAgentOrchestrationContext`** – Wraps an `OrchestrationContext` for use inside orchestrations. `get_agent()` returns a `DurableAIAgent[DurableAgentTask]`.
-- **`AgentEntity`** – Platform-agnostic agent execution logic that manages state, invokes the agent, handles streaming, and calls response callbacks.
-
-## Hosting models
-
-### Azure Functions
-
-The recommended production hosting model. A single call to `ConfigureDurableAgents` (C#) or `AgentFunctionApp` (Python) automatically:
-
-- Registers agent entities with the Durable Task worker.
-- Generates HTTP endpoints at `/api/agents/{agentName}/run` for each registered agent.
-- Supports `thread_id` query parameter / JSON field and the `x-ms-thread-id` response header for session continuity.
-- Supports fire-and-forget via the `x-ms-wait-for-response: false` header (returns HTTP 202).
-- Optionally exposes agents as MCP tools.
-
-**C# example:**
-
-```csharp
-using IHost app = FunctionsApplication
-    .CreateBuilder(args)
-    .ConfigureFunctionsWebApplication()
-    .ConfigureDurableAgents(options => options.AddAIAgent(agent))
-    .Build();
-app.Run();
-```
-
-**Python example:**
-
-```python
-app = AgentFunctionApp(agents=[agent])
-```
-
-### Console apps / generic hosts
-
-For self-hosted or non-serverless scenarios, register durable agents via `IServiceCollection.ConfigureDurableAgents` (.NET) or `DurableAIAgentWorker` (Python) with explicit Durable Task worker and client configuration.
-
-**C# example:**
-
-```csharp
-IHost host = Host.CreateDefaultBuilder(args)
-    .ConfigureServices(services =>
-    {
-        services.ConfigureDurableAgents(
-            options => options.AddAIAgent(agent),
-            workerBuilder: b => b.UseDurableTaskScheduler(connectionString),
-            clientBuilder: b => b.UseDurableTaskScheduler(connectionString));
-    })
-    .Build();
-```
-
-**Python example:**
-
-```python
-worker = DurableAIAgentWorker(TaskHubGrpcWorker(host_address="localhost:4001"))
-worker.add_agent(agent)
-worker.start()
-```
-
-## Deterministic multi-agent orchestrations
-
-Durable agents can be composed into deterministic, checkpointed workflows using Durable Task orchestrations. The orchestration framework replays orchestrator code on failure, so completed agent calls are not re-executed.
-
-### Patterns
-
-| Pattern | Description |
-| --- | --- |
-| **Sequential (chaining)** | Call agents one after another, passing outputs forward. |
-| **Parallel (fan-out/fan-in)** | Run multiple agents concurrently and aggregate results. |
-| **Conditional** | Branch orchestration logic based on structured agent output. |
-| **Human-in-the-loop** | Pause for external events (approvals, feedback) with optional timeouts. |
-
-### Using agents in orchestrations
-
-Inside an orchestration function, obtain a `DurableAIAgent` via the orchestration context. Each agent gets its own session (created with `CreateSessionAsync` / `create_session`), and you can call the same agent multiple times on the same session to maintain conversation context across sequential invocations.
-
-**C#:**
-
-```csharp
-static async Task<string> WritingOrchestration(TaskOrchestrationContext context)
-{
-    // Get a durable agent reference — works in any host (console app, Azure Functions, etc.)
-    DurableAIAgent writer = context.GetAgent("WriterAgent");
-
-    // Create a session to maintain conversation context across multiple calls
-    AgentSession session = await writer.CreateSessionAsync();
-
-    // First call: generate an initial draft
-    AgentResponse<TextResponse> draft = await writer.RunAsync<TextResponse>(
-        message: "Write a concise inspirational sentence about learning.",
-        session: session);
-
-    // Second call: refine the draft — the agent sees the full conversation history
-    AgentResponse<TextResponse> refined = await writer.RunAsync<TextResponse>(
-        message: $"Improve this further while keeping it under 25 words: {draft.Result.Text}",
-        session: session);
-
-    return refined.Result.Text;
-}
-```
-
-**Python:**
-
-```python
-def writing_orchestration(context, _):
-    agent_ctx = DurableAIAgentOrchestrationContext(context)
-
-    # Get a durable agent reference — works in any host (standalone worker, Azure Functions, etc.)
-    writer = agent_ctx.get_agent("WriterAgent")
-
-    # Create a session to maintain conversation context across multiple calls
-    session = writer.create_session()
-
-    # First call: generate an initial draft
-    draft = yield writer.run(
-        messages="Write a concise inspirational sentence about learning.",
-        session=session,
-    )
-
-    # Second call: refine the draft — the agent sees the full conversation history
-    refined = yield writer.run(
-        messages=f"Improve this further while keeping it under 25 words: {draft.text}",
-        session=session,
-    )
-
-    return refined.text
-```
-
-> [!IMPORTANT]
-> In .NET, `DurableAIAgent.RunAsync<T>` deliberately avoids `ConfigureAwait(false)` because the Durable Task Framework uses a custom synchronization context — all continuations must run on the orchestration thread.
-
-## Streaming and response callbacks
-
-Durable agents do not support true end-to-end streaming because entity operations are request/response. However, **reliable streaming** is supported via response callbacks:
-
-- **`IAgentResponseHandler`** (.NET) or **`AgentResponseCallbackProtocol`** (Python) – Implement this interface to receive streaming updates as the underlying agent generates them (e.g., push tokens to a Redis Stream for client consumption).
-- The entity still returns the complete `AgentResponse` after the stream is fully consumed.
-- Clients can reconnect and resume reading from a cursor-based stream (e.g., Redis Streams) without losing messages.
-
-See the **Reliable Streaming** samples for a complete implementation using Redis Streams.
-
-## Session TTL (Time-To-Live)
-
-Durable agent sessions support automatic cleanup via configurable TTL. See [Session TTL](durable-agents-ttl.md) for details on configuration, behavior, and best practices.
-
-## Observability
-
-When using the [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler) as the durable backend, you get built-in observability through its dashboard:
-
-- **Conversation history** – View complete chat history for each agent session.
-- **Orchestration visualization** – See multi-agent execution flows, including parallel branches and conditional logic.
-- **Performance metrics** – Monitor agent response times, token usage, and orchestration duration.
-- **Debugging** – Trace tool invocations and external event handling.
-
-## Samples
-
-- **.NET** – [Console app samples](../../../dotnet/samples/04-hosting/DurableAgents/ConsoleApps/) and [Azure Functions samples](../../../dotnet/samples/04-hosting/DurableAgents/AzureFunctions/) covering single-agent, chaining, concurrency, conditionals, human-in-the-loop, long-running tools, MCP tool exposure, and reliable streaming.
-- **Python** – [Durable Task samples](../../../python/samples/04-hosting/durabletask/) covering single-agent, multi-agent, streaming, chaining, concurrency, conditionals, and human-in-the-loop.
-
-## Packages
-
-| Language | Package | Source |
-| --- | --- | --- |
-| .NET | `Microsoft.Agents.AI.DurableTask` | [`dotnet/src/Microsoft.Agents.AI.DurableTask`](../../../dotnet/src/Microsoft.Agents.AI.DurableTask) |
-| .NET | `Microsoft.Agents.AI.Hosting.AzureFunctions` | [`dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions`](../../../dotnet/src/Microsoft.Agents.AI.Hosting.AzureFunctions) |
-| Python | `agent-framework-durabletask` | [`python/packages/durabletask`](../../../python/packages/durabletask) |
-| Python | `agent-framework-azurefunctions` | [`python/packages/azurefunctions`](../../../python/packages/azurefunctions) |
-
-## Further reading
-
-- [Azure Functions (Durable) — Microsoft Learn](https://learn.microsoft.com/agent-framework/integrations/azure-functions)
-- [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler)
-- [Durable Entities](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-entities)
-- [Session TTL](durable-agents-ttl.md)

docs/features/vector-stores-and-embeddings/README.md

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

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

@@ -125,7 +125,7 @@ The proposed solution is to add helper methods which allow developers to either
 - [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` 
+- [Agent Framework SDK] Invoke the `AIAgent` instance and access response from the `AgentRunResponse` 
 - [Foundry SDK] Clean up the agent
 
 
@@ -156,7 +156,7 @@ await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
 
 - [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` 
+- [Agent Framework SDK] Invoke the `AIAgent` instance and access response from the `AgentRunResponse` 
 - [Foundry SDK] Clean up the agent
 
 ```csharp
@@ -184,7 +184,7 @@ await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
 - [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` 
+- [Agent Framework SDK] Invoke the `AIAgent` instance and access response from the `AgentRunResponse` 
 - [Foundry SDK] Clean up the agent and the agent thread
 
 ```csharp
@@ -227,7 +227,7 @@ await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
 - [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` 
+- [Agent Framework SDK] Invoke the `SequentialOrchestration` instance and access response from the `AgentRunResponse` 
 - [Foundry SDK] Clean up the agents
 
 ```csharp
@@ -281,7 +281,7 @@ SequentialOrchestration orchestration =
 // 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);
+AgentRunResponse result = await orchestration.RunAsync(input);
 Console.WriteLine($"\n# RESULT: {result}");
 
 // Cleanup

dotnet/.github/skills/build-and-test/SKILL.md

@@ -1,85 +0,0 @@
----
-name: build-and-test
-description: How to build and test .NET projects in the Agent Framework repository. Use this when verifying or testing changes.
----
-
-- Only **UnitTest** projects need to be run locally; IntegrationTests require external dependencies.
-- See `../project-structure/SKILL.md` for project structure details.
-
-## Build, Test, and Lint Commands
-
-```bash
-# From dotnet/ directory
-dotnet restore --tl:off   # Restore dependencies for all projects
-dotnet build --tl:off     # Build all projects
-dotnet test               # Run all tests
-dotnet format             # Auto-fix formatting for all projects
-
-# Build/test/format a specific project (preferred for isolated/internal changes)
-dotnet build src/Microsoft.Agents.AI.<Package> --tl:off
-dotnet test tests/Microsoft.Agents.AI.<Package>.UnitTests
-dotnet format src/Microsoft.Agents.AI.<Package>
-
-# Run a single test
-dotnet test --filter "FullyQualifiedName~Namespace.TestClassName.TestMethodName"
-
-# Run unit tests only
-dotnet test --filter FullyQualifiedName\~UnitTests
-```
-
-Use `--tl:off` when building to avoid flickering when running commands in the agent.
-
-## Speeding Up Builds and Testing
-
-The full solution is large. Use these shortcuts:
-
-| Change type | What to do |
-|-------------|------------|
-| Isolated/Internal logic | Build only the affected project and its `*.UnitTests` project. Fix issues, then build the full solution and run all unit tests. |
-| Public API surface | Build the full solution and run all unit tests immediately. |
-
-Example: Building a single code project for all target frameworks
-
-```bash
-# From dotnet/ directory
-dotnet build ./src/Microsoft.Agents.AI.Abstractions
-```
-
-Example: Building a single code project for just .NET 10.
-
-```bash
-# From dotnet/ directory
-dotnet build ./src/Microsoft.Agents.AI.Abstractions -f net10.0
-```
-
-Example: Running tests for a single project using .NET 10.
-
-```bash
-# From dotnet/ directory
-dotnet test ./tests/Microsoft.Agents.AI.Abstractions.UnitTests -f net10.0
-```
-
-Example: Running a single test in a specific project using .NET 10.
-Provide the full namespace, class name, and method name for the test you want to run:
-
-```bash
-# From dotnet/ directory
-dotnet test ./tests/Microsoft.Agents.AI.Abstractions.UnitTests -f net10.0 --filter "FullyQualifiedName~Microsoft.Agents.AI.Abstractions.UnitTests.AgentRunOptionsTests.CloningConstructorCopiesProperties"
-```
-
-### Multi-target framework tip
-
-Most projects target multiple .NET frameworks. If the affected code does **not** use `#if` directives for framework-specific logic, pass `-f net10.0` to speed up building and testing.
-
-### Package Restore tip
-
-`dotnet build` will try and restore packages for all projects on each build, which can be slow.
-Unless packages have been changed, or it's the first time building the solution, add `--no-restore` to the build command to skip this step and speed up builds.
-
-Just remember to run `dotnet restore` after pulling changes, making changes to project references, or when building for the first time.
-
-### Testing on Linux tip
-
-Unit tests target both .NET Framework as well as .NET Core. When running on Linux, only the .NET Core tests can be run, as .NET Framework is not supported on Linux.
-
-To run only the .NET Core tests, use the `-f net10.0` option with `dotnet test`.

dotnet/.github/skills/project-structure/SKILL.md

@@ -1,31 +0,0 @@
----
-name: project-structure
-description: Explains the project structure of the agent-framework .NET solution
----
-
-# Agent Framework .NET Project Structure
-
-```
-dotnet/
-├── src/
-│   ├── Microsoft.Agents.AI/                      # Core AI agent implementations
-│   ├── Microsoft.Agents.AI.Abstractions/         # Core AI agent abstractions
-│   ├── Microsoft.Agents.AI.A2A/                  # Agent-to-Agent (A2A) provider
-│   ├── Microsoft.Agents.AI.OpenAI/               # OpenAI provider
-│   ├── Microsoft.Agents.AI.AzureAI/              # Azure AI Foundry Agents (v2) provider
-│   ├── Microsoft.Agents.AI.AzureAI.Persistent/   # Legacy Azure AI Foundry Agents (v1) provider
-│   ├── Microsoft.Agents.AI.Anthropic/            # Anthropic provider
-│   ├── Microsoft.Agents.AI.Workflows/            # Workflow orchestration
-│   └── ...                                       # Other packages
-├── samples/                                      # Sample applications
-└── tests/                                        # Unit and integration tests
-```
-
-## Main Folders
-
-| Folder | Contents |
-|--------|----------|
-| `src/` | Source code projects |
-| `tests/` | Test projects — named `<Source-Code-Project>.UnitTests` or `<Source-Code-Project>.IntegrationTests` |
-| `samples/` | Sample projects |
-| `src/Shared`, `src/LegacySupport` | Shared code files included by multiple source code projects (see README.md files in these folders or their subdirectories for instructions on how to include them in a project) |

dotnet/.github/skills/verify-dotnet-samples/SKILL.md

@@ -1,82 +0,0 @@
----
-name: verify-dotnet-samples
-description: How to build, run and verify the .NET sample projects in the Agent Framework repository. Use this when a user wants to verify that the samples still function as expected.
----
-
-# Verifying .NET Sample Projects
-
-## Sample Pre-requisites
-
-We should only support verifying samples that:
-1. Use environment variables for configuration.
-2. Have no complex setup requirements, e.g., where multiple applications need to be run together, or where we need to launch a browser, etc.
-
-Always report to the user which samples were run and which were not, and why.
-
-## Verifying a sample
-
-Samples should be verified to ensure that they actually work as intended and that their output matches what is expected.
-For each sample that is run, output should be produced that shows the result and explains the reasoning about what output
-was expected, what was produced, and why it didn't match what the sample was expected to produce.
-
-Steps to verify a sample:
-1. Read the code for the sample
-1. Check what environment variables are required for the sample
-1. Check if each environment variable has been set
-1. If there are any missing, give the user a list of missing environment variables to set and terminate
-1. Summarize what the expected output of the sample should be
-1. Run the sample
-1. Show the user any output from the sample run as it gets produced, so that they can see the run progress
-1. Check the output of the run against expectations
-1. After running all requested samples, produce output for each sample that was verified:
-  1. If expectations were matched, output the following:
-     ```text
-     [Sample Name] Succeeded
-     ```
-  1. If expectations were not matched, output the following:
-     ```text
-     [Sample Name] Failed
-     Actual Output:
-     [What the sample produced]
-     Expected Output:
-     [Explanation of what was expected and why the actual output didn't match expectations]
-     ```
-
-## Environment Variables
-
-Most samples use environment variables to configure settings.
-
-```csharp
-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";
-```
-
-To run a sample, the environment variables should be set first.
-Before running a sample, check whether each environment variable in the sample has a value and
-then give the user a list of environment variables to set.
-
-You can provide the user some examples of how to set the variables like this:
-
-```bash
-export AZURE_OPENAI_ENDPOINT="https://my-openai-instance.openai.azure.com/"
-export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
-```
-
-To check if a variable has a value use e.g.:
-
-```bash
-echo $AZURE_OPENAI_ENDPOINT
-```
-
-## How to Run a Sample (General Pattern)
-
-```bash
-cd dotnet/samples/<category>/<sample-dir>
-dotnet run
-```
-
-For multi-targeted projects (e.g., Durable console apps), specify the framework:
-
-```bash
-dotnet run --framework net10.0
-```

dotnet/.vscode/settings.json

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

dotnet/AGENTS.md

@@ -1,66 +0,0 @@
-# AGENTS.md
-
-Instructions for AI coding agents working in the .NET codebase.
-
-## Build, Test, and Lint Commands
-
-See `./.github/skills/build-and-test/SKILL.md` for detailed instructions on building, testing, and linting projects.
-
-## Project Structure
-
-See `./.github/skills/project-structure/SKILL.md` for an overview of the project structure.
-
-### Core types
-
-- `AIAgent`: The abstract base class that all agents derive from, providing common methods for interacting with an agent.
-- `AgentSession`: The abstract base class that all agent sessions derive from, representing a conversation with an agent.
-- `ChatClientAgent`: An `AIAgent` implementation that uses an `IChatClient` to send messages to an AI provider and receive responses.
-- `IChatClient`: Interface for sending messages to an AI provider and receiving responses. Used by `ChatClientAgent` and implemented by provider-specific packages.
-- `FunctionInvokingChatClient`: Decorator for `IChatClient` that adds function invocation capabilities.
-- `AITool`: Represents a tool that an agent/AI provider can use, with metadata and an execution delegate.
-- `AIFunction`: A specific type of `AITool` that represents a local function the agent/AI provider can call, with parameters and return types defined.
-- `ChatMessage`: Represents a message in a conversation.
-- `AIContent`: Represents content in a message, which can be text, a function call, tool output and more.
-
-### External Dependencies
-
-The framework integrates with `Microsoft.Extensions.AI` and `Microsoft.Extensions.AI.Abstractions` (external NuGet packages)
-using types like `IChatClient`, `FunctionInvokingChatClient`, `AITool`, `AIFunction`, `ChatMessage`, and `AIContent`.
-
-## Key Conventions
-
-- **Encoding**: All new files must be saved with UTF-8 encoding with BOM (Byte Order Mark). This is required for `dotnet format` to work correctly.
-- **Copyright header**: `// Copyright (c) Microsoft. All rights reserved.` at top of all `.cs` files
-- **XML docs**: Required for all public methods and classes
-- **Async**: Use `Async` suffix for methods returning `Task`/`ValueTask`
-- **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
-
-## Key Design Principles
-
-When developing or reviewing code, verify adherence to these key design principles:
-
-- **DRY**: Avoid code duplication by moving common logic into helper methods or helper classes.
-- **Single Responsibility**: Each class should have one clear responsibility.
-- **Encapsulation**: Keep implementation details private and expose only necessary public APIs.
-- **Strong Typing**: Use strong typing to ensure that code is self-documenting and to catch errors at compile time.
-
-## Sample Structure
-
-Samples (in `./samples/` folder) should follow this 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.Packages.props

@@ -11,40 +11,40 @@
   </PropertyGroup>
   <ItemGroup>
     <!-- Aspire.* -->
-    <PackageVersion Include="Anthropic" Version="12.3.0" />
-    <PackageVersion Include="Anthropic.Foundry" Version="0.4.1" />
+    <PackageVersion Include="Anthropic" Version="12.0.1" />
+    <PackageVersion Include="Anthropic.Foundry" Version="0.1.0" />
     <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="13.0.0-preview.1.25560.3" />
     <PackageVersion Include="Aspire.Hosting.AppHost" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Hosting.Azure.CognitiveServices" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0" />
     <!-- Azure.* -->
-    <PackageVersion Include="Azure.AI.Projects" Version="2.0.0-beta.1" />
-    <PackageVersion Include="Azure.AI.Projects.OpenAI" Version="2.0.0-beta.1" />
+    <PackageVersion Include="Azure.AI.Projects" Version="1.2.0-beta.5" />
+    <PackageVersion Include="Azure.AI.Projects.OpenAI" Version="1.0.0-beta.5" />
     <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.8" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="2.8.0-beta.1" />
     <PackageVersion Include="Azure.Identity" Version="1.17.1" />
     <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.4.0" />
     <!-- Google Gemini  -->
-    <PackageVersion Include="Google.GenAI" Version="0.11.0" />
+    <PackageVersion Include="Google.GenAI" Version="0.9.0" />
     <PackageVersion Include="Mscc.GenerativeAI.Microsoft" Version="2.9.3" />
     <!-- Microsoft.Azure.* -->
     <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.54.0" />
     <!-- Newtonsoft.Json -->
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
     <!-- System.* -->
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.3" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
-    <PackageVersion Include="System.ClientModel" Version="1.9.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.8.1" />
     <PackageVersion Include="System.CodeDom" Version="10.0.0" />
-    <PackageVersion Include="System.Collections.Immutable" Version="10.0.1" />
+    <PackageVersion Include="System.Collections.Immutable" Version="10.0.0" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
-    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.3" />
+    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="10.0.1" />
     <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.0" />
     <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />
-    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.3" />
-    <PackageVersion Include="System.Text.Json" Version="10.0.3" />
-    <PackageVersion Include="System.Threading.Channels" Version="10.0.3" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.0" />
+    <PackageVersion Include="System.Text.Json" Version="10.0.1" />
+    <PackageVersion Include="System.Threading.Channels" Version="10.0.1" />
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
     <PackageVersion Include="System.Net.Security" Version="4.3.2" />
     <!-- OpenTelemetry -->
@@ -58,17 +58,12 @@
     <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.13.0" />
     <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.13.0" />
     <!-- Microsoft.AspNetCore.* -->
-    <PackageVersion Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="10.0.0" />
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
     <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
     <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.3.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.3.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation" Version="10.3.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Quality" Version="10.3.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Evaluation.Safety" Version="10.3.0-preview.1.26109.11" />
-    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.3.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI" Version="10.1.1" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.1.1" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.1.1-preview.1.25612.2" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.0" />
@@ -76,11 +71,11 @@
     <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.3" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.0" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.3" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
@@ -94,7 +89,6 @@
     <PackageVersion Include="Microsoft.SemanticKernel.Agents.AzureAI" Version="1.67.0-preview" />
     <PackageVersion Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.67.0" />
     <!-- Agent SDKs -->
-    <PackageVersion Include="GitHub.Copilot.SDK" Version="0.1.29" />
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.3.171-beta" />
     <!-- M365 Agents SDK -->
     <PackageVersion Include="AdaptiveCards" Version="3.1.0" />
@@ -104,7 +98,7 @@
     <PackageVersion Include="A2A" Version="0.3.3-preview" />
     <PackageVersion Include="A2A.AspNetCore" Version="0.3.3-preview" />
     <!-- MCP -->
-    <PackageVersion Include="ModelContextProtocol" Version="0.8.0-preview.1" />
+    <PackageVersion Include="ModelContextProtocol" Version="0.4.0-preview.3" />
     <!-- Inference SDKs -->
     <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.5.1" />
     <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
@@ -113,19 +107,19 @@
     <!-- Identity -->
     <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.78.0" />
     <!-- Workflows -->
-    <PackageVersion Include="Microsoft.Agents.ObjectModel" Version="2026.2.4.1" />
-    <PackageVersion Include="Microsoft.Agents.ObjectModel.Json" Version="2026.2.4.1" />
-    <PackageVersion Include="Microsoft.Agents.ObjectModel.PowerFx" Version="2026.2.4.1" />
-    <PackageVersion Include="Microsoft.PowerFx.Interpreter" Version="1.8.1" />
+    <PackageVersion Include="Microsoft.Bot.ObjectModel" Version="1.2025.1106.1" />
+    <PackageVersion Include="Microsoft.Bot.ObjectModel.Json" Version="1.2025.1106.1" />
+    <PackageVersion Include="Microsoft.Bot.ObjectModel.PowerFx" Version="1.2025.1106.1" />
+    <PackageVersion Include="Microsoft.PowerFx.Interpreter" Version="1.5.0-build.20251008-1002" />
     <!-- Durable Task -->
-    <PackageVersion Include="Microsoft.DurableTask.Client" Version="1.18.0" />
-    <PackageVersion Include="Microsoft.DurableTask.Client.AzureManaged" Version="1.18.0" />
-    <PackageVersion Include="Microsoft.DurableTask.Worker" Version="1.18.0" />
-    <PackageVersion Include="Microsoft.DurableTask.Worker.AzureManaged" Version="1.18.0" />
+    <PackageVersion Include="Microsoft.DurableTask.Client" Version="1.19.1" />
+    <PackageVersion Include="Microsoft.DurableTask.Client.AzureManaged" Version="1.19.0" />
+    <PackageVersion Include="Microsoft.DurableTask.Worker" Version="1.19.0" />
+    <PackageVersion Include="Microsoft.DurableTask.Worker.AzureManaged" Version="1.19.0" />
     <!-- Azure Functions -->
     <PackageVersion Include="Microsoft.Azure.Functions.Worker" Version="2.50.0" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="2.50.0" />
-    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" Version="1.11.0" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" Version="1.13.1" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" Version="1.0.1" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.3.0" />
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="2.1.0" />
@@ -149,7 +143,6 @@
     <!-- Symbols -->
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
     <!-- Toolset -->
-    <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="3.11.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.100" />
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers">
@@ -187,4 +180,4 @@
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
     </PackageReference>
   </ItemGroup>
-</Project>
+</Project>

dotnet/README.md

@@ -1,30 +1,36 @@
 # Get Started with Microsoft Agent Framework for C# Developers
 
+## Samples
+
+- [Getting Started with Agents](./samples/GettingStarted/Agents): basic agent creation and tool usage
+- [Agent Provider Samples](./samples/GettingStarted/AgentProviders): samples showing different agent providers
+- [Workflow Samples](./samples/GettingStarted/Workflows): advanced multi-agent patterns and workflow orchestration
+
 ## Quickstart
 
 ### Basic Agent - .NET
 
 ```c#
+using System;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using OpenAI.Responses;
 
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!;
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")!;
 
 var agent = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
-    .GetResponsesClient(deploymentName)
-    .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
+    .GetOpenAIResponseClient(deploymentName)
+    .CreateAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");
 
 Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
 ```
 
 ## Examples & Samples
 
-- [Getting Started with Agents](./samples/02-agents/Agents): basic agent creation and tool usage
-- [Agent Provider Samples](./samples/02-agents/AgentProviders): samples showing different agent providers
-- [Workflow Samples](./samples/03-workflows): advanced multi-agent patterns and workflow orchestration
+- [Getting Started with Agents](./samples/GettingStarted/Agents): basic agent creation and tool usage
+- [Agent Provider Samples](./samples/GettingStarted/AgentProviders): samples showing different agent providers
+- [Workflow Samples](./samples/GettingStarted/Workflows): advanced multi-agent patterns and workflow orchestration
 
 ## Agent Framework Documentation
 

dotnet/agent-framework-dotnet.slnx

@@ -5,189 +5,208 @@
     <BuildType Name="Release" />
   </Configurations>
   <Folder Name="/Samples/">
-    <File Path="samples/AGENTS.md" />
     <File Path="samples/README.md" />
   </Folder>
-  <Folder Name="/Samples/01-get-started/">
-    <Project Path="samples/01-get-started/01_hello_agent/01_hello_agent.csproj" />
-    <Project Path="samples/01-get-started/02_add_tools/02_add_tools.csproj" />
-    <Project Path="samples/01-get-started/03_multi_turn/03_multi_turn.csproj" />
-    <Project Path="samples/01-get-started/04_memory/04_memory.csproj" />
-    <Project Path="samples/01-get-started/05_first_workflow/05_first_workflow.csproj" />
-    <Project Path="samples/01-get-started/06_host_your_agent/06_host_your_agent.csproj" />
+  <Folder Name="/Samples/A2AClientServer/">
+    <File Path="samples/A2AClientServer/README.md" />
+    <Project Path="samples/A2AClientServer/A2AClient/A2AClient.csproj" />
+    <Project Path="samples/A2AClientServer/A2AServer/A2AServer.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/">
-    <File Path="samples/02-agents/README.md" />
+  <Folder Name="/Samples/AgentWebChat/">
+    <Project Path="samples/AgentWebChat/AgentWebChat.AgentHost/AgentWebChat.AgentHost.csproj" />
+    <Project Path="samples/AgentWebChat/AgentWebChat.AppHost/AgentWebChat.AppHost.csproj" />
+    <Project Path="samples/AgentWebChat/AgentWebChat.ServiceDefaults/AgentWebChat.ServiceDefaults.csproj" />
+    <Project Path="samples/AgentWebChat/AgentWebChat.Web/AgentWebChat.Web.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentProviders/">
-    <File Path="samples/02-agents/AgentProviders/README.md" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_A2A/Agent_With_A2A.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_Anthropic/Agent_With_Anthropic.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureAIAgentsPersistent/Agent_With_AzureAIAgentsPersistent.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureAIProject/Agent_With_AzureAIProject.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureFoundryModel/Agent_With_AzureFoundryModel.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Agent_With_AzureOpenAIChatCompletion.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_AzureOpenAIResponses/Agent_With_AzureOpenAIResponses.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_CustomImplementation/Agent_With_CustomImplementation.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/Agent_With_GitHubCopilot.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_Ollama/Agent_With_Ollama.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_ONNX/Agent_With_ONNX.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIAssistants/Agent_With_OpenAIAssistants.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIChatCompletion/Agent_With_OpenAIChatCompletion.csproj" />
-    <Project Path="samples/02-agents/AgentProviders/Agent_With_OpenAIResponses/Agent_With_OpenAIResponses.csproj" />
+  <Folder Name="/Samples/AGUIClientServer/">
+    <Project Path="samples/AGUIClientServer/AGUIClient/AGUIClient.csproj" />
+    <Project Path="samples/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj" />
+    <Project Path="samples/AGUIClientServer/AGUIServer/AGUIServer.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/Agents/">
-    <File Path="samples/02-agents/Agents/README.md" />
-    <Project Path="samples/02-agents/Agents/Agent_Step01_UsingFunctionToolsWithApprovals/Agent_Step01_UsingFunctionToolsWithApprovals.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step02_StructuredOutput/Agent_Step02_StructuredOutput.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step03_PersistedConversations/Agent_Step03_PersistedConversations.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step04_3rdPartyChatHistoryStorage/Agent_Step04_3rdPartyChatHistoryStorage.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step05_Observability/Agent_Step05_Observability.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step06_DependencyInjection/Agent_Step06_DependencyInjection.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step07_AsMcpTool/Agent_Step07_AsMcpTool.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step08_UsingImages/Agent_Step08_UsingImages.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step09_AsFunctionTool/Agent_Step09_AsFunctionTool.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step10_BackgroundResponsesWithToolsAndPersistence/Agent_Step10_BackgroundResponsesWithToolsAndPersistence.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step11_Middleware/Agent_Step11_Middleware.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step12_Plugins/Agent_Step12_Plugins.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step13_ChatReduction/Agent_Step13_ChatReduction.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step14_BackgroundResponses/Agent_Step14_BackgroundResponses.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step15_DeepResearch/Agent_Step15_DeepResearch.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step16_Declarative/Agent_Step16_Declarative.csproj" />
-    <Project Path="samples/02-agents/Agents/Agent_Step17_AdditionalAIContext/Agent_Step17_AdditionalAIContext.csproj" />
+  <Folder Name="/Samples/AzureFunctions/">
+    <File Path="samples/AzureFunctions/.editorconfig" />
+    <File Path="samples/AzureFunctions/README.md" />
+    <Project Path="samples/AzureFunctions/01_SingleAgent/01_SingleAgent.csproj" />
+    <Project Path="samples/AzureFunctions/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
+    <Project Path="samples/AzureFunctions/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
+    <Project Path="samples/AzureFunctions/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
+    <Project Path="samples/AzureFunctions/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
+    <Project Path="samples/AzureFunctions/06_LongRunningTools/06_LongRunningTools.csproj" />
+    <Project Path="samples/AzureFunctions/07_AgentAsMcpTool/07_AgentAsMcpTool.csproj" />
+    <Project Path="samples/AzureFunctions/08_ReliableStreaming/08_ReliableStreaming.csproj" />
+    <Project Path="samples/AzureFunctions/09_Workflow/09_Workflow.csproj" />
+    <Project Path="samples/AzureFunctions/10_WorkflowConcurrent/10_WorkflowConcurrent.csproj" />
+    <Project Path="samples/AzureFunctions/11_WorkflowSharedState/11_WorkflowSharedState.csproj" />
+    <Project Path="samples/AzureFunctions/12_ConditionalEdges/12_ConditionalEdges.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/DeclarativeAgents/">
-    <Project Path="samples/02-agents/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
+  <Folder Name="/Samples/DurableWorkflows/">
+    <Project Path="samples/DurableWorkflows/01_ExecutorsAndEdges/01_ExecutorsAndEdges.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/">
-    <File Path="samples/02-agents/AGUI/README.md" />
+  <Folder Name="/Samples/GettingStarted/">
+    <File Path="samples/GettingStarted/README.md" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/Step01_GettingStarted/">
-    <Project Path="samples/02-agents/AGUI/Step01_GettingStarted/Client/Client.csproj" />
-    <Project Path="samples/02-agents/AGUI/Step01_GettingStarted/Server/Server.csproj" />
+  <Folder Name="/Samples/GettingStarted/A2A/">
+    <File Path="samples/GettingStarted/A2A/README.md" />
+    <Project Path="samples/GettingStarted/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
+    <Project Path="samples/GettingStarted/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/Step02_BackendTools/">
-    <Project Path="samples/02-agents/AGUI/Step02_BackendTools/Client/Client.csproj" />
-    <Project Path="samples/02-agents/AGUI/Step02_BackendTools/Server/Server.csproj" />
+  <Folder Name="/Samples/GettingStarted/AgentProviders/">
+    <File Path="samples/GettingStarted/AgentProviders/README.md" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_A2A/Agent_With_A2A.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_Anthropic/Agent_With_Anthropic.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureAIAgentsPersistent/Agent_With_AzureAIAgentsPersistent.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureAIProject/Agent_With_AzureAIProject.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureFoundryModel/Agent_With_AzureFoundryModel.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIChatCompletion/Agent_With_AzureOpenAIChatCompletion.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_AzureOpenAIResponses/Agent_With_AzureOpenAIResponses.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_CustomImplementation/Agent_With_CustomImplementation.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_GoogleGemini/Agent_With_GoogleGemini.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_Ollama/Agent_With_Ollama.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_ONNX/Agent_With_ONNX.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIAssistants/Agent_With_OpenAIAssistants.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIChatCompletion/Agent_With_OpenAIChatCompletion.csproj" />
+    <Project Path="samples/GettingStarted/AgentProviders/Agent_With_OpenAIResponses/Agent_With_OpenAIResponses.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/Step03_FrontendTools/">
-    <Project Path="samples/02-agents/AGUI/Step03_FrontendTools/Client/Client.csproj" />
-    <Project Path="samples/02-agents/AGUI/Step03_FrontendTools/Server/Server.csproj" />
+  <Folder Name="/Samples/GettingStarted/Agents/">
+    <File Path="samples/GettingStarted/Agents/README.md" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step01_Running/Agent_Step01_Running.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step02_MultiturnConversation/Agent_Step02_MultiturnConversation.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step03_UsingFunctionTools/Agent_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step04_UsingFunctionToolsWithApprovals/Agent_Step04_UsingFunctionToolsWithApprovals.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Agent_Step05_StructuredOutput.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step06_PersistedConversations/Agent_Step06_PersistedConversations.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step07_3rdPartyThreadStorage/Agent_Step07_3rdPartyThreadStorage.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step08_Observability/Agent_Step08_Observability.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step09_DependencyInjection/Agent_Step09_DependencyInjection.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step10_AsMcpTool/Agent_Step10_AsMcpTool.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step11_UsingImages/Agent_Step11_UsingImages.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step12_AsFunctionTool/Agent_Step12_AsFunctionTool.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step13_BackgroundResponsesWithToolsAndPersistence/Agent_Step13_BackgroundResponsesWithToolsAndPersistence.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step14_Middleware/Agent_Step14_Middleware.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step15_Plugins/Agent_Step15_Plugins.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step16_ChatReduction/Agent_Step16_ChatReduction.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/Agent_Step17_BackgroundResponses.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step18_DeepResearch/Agent_Step18_DeepResearch.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step19_Declarative/Agent_Step19_Declarative.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/Step04_HumanInLoop/">
-    <Project Path="samples/02-agents/AGUI/Step04_HumanInLoop/Client/Client.csproj" />
-    <Project Path="samples/02-agents/AGUI/Step04_HumanInLoop/Server/Server.csproj" />
+  <Folder Name="/Samples/GettingStarted/DeclarativeAgents/">
+    <Project Path="samples/GettingStarted/DeclarativeAgents/ChatClient/DeclarativeChatClientAgents.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentSkills/">
-    <File Path="samples/02-agents/AgentSkills/README.md" />
-    <Project Path="samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Agent_Step01_BasicSkills.csproj" />
+  <Folder Name="/Samples/GettingStarted/AGUI/">
+    <File Path="samples/GettingStarted/AGUI/README.md" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AGUI/Step05_StateManagement/">
-    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Client/Client.csproj" />
-    <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Server/Server.csproj" />
+  <Folder Name="/Samples/GettingStarted/AGUI/Step01_GettingStarted/">
+    <Project Path="samples/GettingStarted/AGUI/Step01_GettingStarted/Client/Client.csproj" />
+    <Project Path="samples/GettingStarted/AGUI/Step01_GettingStarted/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/DevUI/">
-    <File Path="samples/02-agents/DevUI/README.md" />
-    <Project Path="samples/02-agents/DevUI/DevUI_Step01_BasicUsage/DevUI_Step01_BasicUsage.csproj" />
+  <Folder Name="/Samples/GettingStarted/AGUI/Step02_BackendTools/">
+    <Project Path="samples/GettingStarted/AGUI/Step02_BackendTools/Client/Client.csproj" />
+    <Project Path="samples/GettingStarted/AGUI/Step02_BackendTools/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentWithAnthropic/">
-    <File Path="samples/02-agents/AgentWithAnthropic/README.md" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step01_Running/Agent_Anthropic_Step01_Running.csproj" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning/Agent_Anthropic_Step02_Reasoning.csproj" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/Agent_Anthropic_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj" />
+  <Folder Name="/Samples/GettingStarted/AGUI/Step03_FrontendTools/">
+    <Project Path="samples/GettingStarted/AGUI/Step03_FrontendTools/Client/Client.csproj" />
+    <Project Path="samples/GettingStarted/AGUI/Step03_FrontendTools/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentWithMemory/">
-    <File Path="samples/02-agents/AgentWithMemory/README.md" />
-    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/AgentWithMemory_Step01_ChatHistoryMemory.csproj" />
-    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/AgentWithMemory_Step02_MemoryUsingMem0.csproj" />
-    <Project Path="samples/02-agents/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/AgentWithMemory_Step04_MemoryUsingFoundry.csproj" />
+  <Folder Name="/Samples/GettingStarted/AGUI/Step04_HumanInLoop/">
+    <Project Path="samples/GettingStarted/AGUI/Step04_HumanInLoop/Client/Client.csproj" />
+    <Project Path="samples/GettingStarted/AGUI/Step04_HumanInLoop/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentWithOpenAI/">
-    <File Path="samples/02-agents/AgentWithOpenAI/README.md" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step01_Running/Agent_OpenAI_Step01_Running.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Agent_OpenAI_Step02_Reasoning.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj" />
-    <Project Path="samples/02-agents/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj" />
+  <Folder Name="/Samples/GettingStarted/AGUI/Step05_StateManagement/">
+    <Project Path="samples/GettingStarted/AGUI/Step05_StateManagement/Client/Client.csproj" />
+    <Project Path="samples/GettingStarted/AGUI/Step05_StateManagement/Server/Server.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/AgentWithRAG/">
-    <File Path="samples/02-agents/AgentWithRAG/README.md" />
-    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/AgentWithRAG_Step01_BasicTextRAG.csproj" />
-    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/AgentWithRAG_Step02_CustomVectorStoreRAG.csproj" />
-    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/AgentWithRAG_Step03_CustomRAGDataSource.csproj" />
-    <Project Path="samples/02-agents/AgentWithRAG/AgentWithRAG_Step04_FoundryServiceRAG/AgentWithRAG_Step04_FoundryServiceRAG.csproj" />
+  <Folder Name="/Samples/GettingStarted/DevUI/">
+    <File Path="samples/GettingStarted/DevUI/README.md" />
+    <Project Path="samples/GettingStarted/DevUI/DevUI_Step01_BasicUsage/DevUI_Step01_BasicUsage.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/FoundryAgents/">
-    <File Path="samples/02-agents/FoundryAgents/README.md" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming/FoundryAgents_Evaluations_Step01_RedTeaming.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/FoundryAgents_Evaluations_Step02_SelfReflection.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step01.1_Basics/FoundryAgents_Step01.1_Basics.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step01.2_Running/FoundryAgents_Step01.2_Running.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/FoundryAgents_Step02_MultiturnConversation.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step03_UsingFunctionTools/FoundryAgents_Step03_UsingFunctionTools.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step04_UsingFunctionToolsWithApprovals/FoundryAgents_Step04_UsingFunctionToolsWithApprovals.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step05_StructuredOutput/FoundryAgents_Step05_StructuredOutput.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step06_PersistedConversations/FoundryAgents_Step06_PersistedConversations.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step07_Observability/FoundryAgents_Step07_Observability.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step08_DependencyInjection/FoundryAgents_Step08_DependencyInjection.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step09_UsingMcpClientAsTools/FoundryAgents_Step09_UsingMcpClientAsTools.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step10_UsingImages/FoundryAgents_Step10_UsingImages.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step11_AsFunctionTool/FoundryAgents_Step11_AsFunctionTool.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step12_Middleware/FoundryAgents_Step12_Middleware.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step13_Plugins/FoundryAgents_Step13_Plugins.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step14_CodeInterpreter/FoundryAgents_Step14_CodeInterpreter.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step15_ComputerUse/FoundryAgents_Step15_ComputerUse.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step16_FileSearch/FoundryAgents_Step16_FileSearch.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step17_OpenAPITools/FoundryAgents_Step17_OpenAPITools.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step18_BingCustomSearch/FoundryAgents_Step18_BingCustomSearch.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step19_SharePoint/FoundryAgents_Step19_SharePoint.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step20_MicrosoftFabric/FoundryAgents_Step20_MicrosoftFabric.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step21_WebSearch/FoundryAgents_Step21_WebSearch.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step22_MemorySearch/FoundryAgents_Step22_MemorySearch.csproj" />
-    <Project Path="samples/02-agents/FoundryAgents/FoundryAgents_Step23_LocalMCP/FoundryAgents_Step23_LocalMCP.csproj" />
+  <Folder Name="/Samples/GettingStarted/AgentWithAnthropic/">
+    <File Path="samples/GettingStarted/AgentWithAnthropic/README.md" />
+    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step01_Running/Agent_Anthropic_Step01_Running.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step02_Reasoning/Agent_Anthropic_Step02_Reasoning.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithAnthropic/Agent_Anthropic_Step03_UsingFunctionTools/Agent_Anthropic_Step03_UsingFunctionTools.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/ModelContextProtocol/">
-    <File Path="samples/02-agents/ModelContextProtocol/README.md" />
-    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
-    <Project Path="samples/02-agents/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
-    <Project Path="samples/02-agents/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
-    <Project Path="samples/02-agents/ModelContextProtocol/ResponseAgent_Hosted_MCP/ResponseAgent_Hosted_MCP.csproj" />
+  <Folder Name="/Samples/GettingStarted/AgentWithMemory/">
+    <File Path="samples/GettingStarted/AgentWithMemory/README.md" />
+    <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/AgentWithMemory_Step01_ChatHistoryMemory.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/AgentWithMemory_Step02_MemoryUsingMem0.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step03_CustomMemory/AgentWithMemory_Step03_CustomMemory.csproj" />
   </Folder>
-  <Folder Name="/Samples/02-agents/Observability/">
-    <Project Path="samples/02-agents/AgentOpenTelemetry/AgentOpenTelemetry.csproj" />
+  <Folder Name="/Samples/GettingStarted/AgentWithOpenAI/">
+    <File Path="samples/GettingStarted/AgentWithOpenAI/README.md" />
+    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step01_Running/Agent_OpenAI_Step01_Running.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Agent_OpenAI_Step02_Reasoning.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step03_CreateFromChatClient/Agent_OpenAI_Step03_CreateFromChatClient.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient/Agent_OpenAI_Step04_CreateFromOpenAIResponseClient.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step05_Conversation/Agent_OpenAI_Step05_Conversation.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/">
-    <File Path="samples/03-workflows/README.md" />
+  <Folder Name="/Samples/Purview/" />
+  <Folder Name="/Samples/Purview/AgentWithPurview/">
+    <Project Path="samples/Purview/AgentWithPurview/AgentWithPurview.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Concurrent/">
-    <Project Path="samples/03-workflows/Concurrent/Concurrent/Concurrent.csproj" />
-    <Project Path="samples/03-workflows/Concurrent/MapReduce/MapReduce.csproj" />
+  <Folder Name="/Samples/GettingStarted/AgentWithRAG/">
+    <File Path="samples/GettingStarted/AgentWithRAG/README.md" />
+    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/AgentWithRAG_Step01_BasicTextRAG.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/AgentWithRAG_Step02_CustomVectorStoreRAG.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/AgentWithRAG_Step03_CustomRAGDataSource.csproj" />
+    <Project Path="samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step04_FoundryServiceRAG/AgentWithRAG_Step04_FoundryServiceRAG.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/ConditionalEdges/">
-    <Project Path="samples/03-workflows/ConditionalEdges/01_EdgeCondition/01_EdgeCondition.csproj" />
-    <Project Path="samples/03-workflows/ConditionalEdges/02_SwitchCase/02_SwitchCase.csproj" />
-    <Project Path="samples/03-workflows/ConditionalEdges/03_MultiSelection/03_MultiSelection.csproj" />
+  <Folder Name="/Samples/GettingStarted/FoundryAgents/">
+    <File Path="samples/GettingStarted/FoundryAgents/README.md" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.1_Basics/FoundryAgents_Step01.1_Basics.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step01.2_Running/FoundryAgents_Step01.2_Running.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/FoundryAgents_Step02_MultiturnConversation.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step03_UsingFunctionTools/FoundryAgents_Step03_UsingFunctionTools.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step04_UsingFunctionToolsWithApprovals/FoundryAgents_Step04_UsingFunctionToolsWithApprovals.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step05_StructuredOutput/FoundryAgents_Step05_StructuredOutput.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step06_PersistedConversations/FoundryAgents_Step06_PersistedConversations.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step07_Observability/FoundryAgents_Step07_Observability.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step08_DependencyInjection/FoundryAgents_Step08_DependencyInjection.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step09_UsingMcpClientAsTools/FoundryAgents_Step09_UsingMcpClientAsTools.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step10_UsingImages/FoundryAgents_Step10_UsingImages.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step11_AsFunctionTool/FoundryAgents_Step11_AsFunctionTool.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step12_Middleware/FoundryAgents_Step12_Middleware.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step13_Plugins/FoundryAgents_Step13_Plugins.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step14_CodeInterpreter/FoundryAgents_Step14_CodeInterpreter.csproj" />
+    <Project Path="samples/GettingStarted/FoundryAgents/FoundryAgents_Step15_ComputerUse/FoundryAgents_Step15_ComputerUse.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Declarative/">
-    <File Path="samples/03-workflows/Declarative/README.md" />
-    <Project Path="samples/03-workflows/Declarative/ConfirmInput/ConfirmInput.csproj" />
-    <Project Path="samples/03-workflows/Declarative/CustomerSupport/CustomerSupport.csproj" />
-    <Project Path="samples/03-workflows/Declarative/DeepResearch/DeepResearch.csproj" />
-    <Project Path="samples/03-workflows/Declarative/ExecuteCode/ExecuteCode.csproj" />
-    <Project Path="samples/03-workflows/Declarative/ExecuteWorkflow/ExecuteWorkflow.csproj" />
-    <Project Path="samples/03-workflows/Declarative/FunctionTools/FunctionTools.csproj" />
-    <Project Path="samples/03-workflows/Declarative/GenerateCode/GenerateCode.csproj" />
-    <Project Path="samples/03-workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
-    <Project Path="samples/03-workflows/Declarative/InputArguments/InputArguments.csproj" />
-    <Project Path="samples/03-workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj" />
-    <Project Path="samples/03-workflows/Declarative/InvokeMcpTool/InvokeMcpTool.csproj" />
-    <Project Path="samples/03-workflows/Declarative/Marketing/Marketing.csproj" />
-    <Project Path="samples/03-workflows/Declarative/StudentTeacher/StudentTeacher.csproj" />
-    <Project Path="samples/03-workflows/Declarative/ToolApproval/ToolApproval.csproj" />
+  <Folder Name="/Samples/GettingStarted/ModelContextProtocol/">
+    <File Path="samples/GettingStarted/ModelContextProtocol/README.md" />
+    <Project Path="samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
+    <Project Path="samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
+    <Project Path="samples/GettingStarted/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
+    <Project Path="samples/GettingStarted/ModelContextProtocol/ResponseAgent_Hosted_MCP/ResponseAgent_Hosted_MCP.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Declarative/Examples/">
+  <Folder Name="/Samples/GettingStarted/Observability/">
+    <Project Path="samples/GettingStarted/AgentOpenTelemetry/AgentOpenTelemetry.csproj" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/">
+    <File Path="samples/GettingStarted/Workflows/README.md" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/Concurrent/">
+    <Project Path="samples/GettingStarted/Workflows/Concurrent/Concurrent/Concurrent.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Concurrent/MapReduce/MapReduce.csproj" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/ConditionalEdges/">
+    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/01_EdgeCondition/01_EdgeCondition.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/02_SwitchCase/02_SwitchCase.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/ConditionalEdges/03_MultiSelection/03_MultiSelection.csproj" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/Declarative/">
+    <File Path="samples/GettingStarted/Workflows/Declarative/README.md" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/ConfirmInput/ConfirmInput.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/CustomerSupport/CustomerSupport.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/DeepResearch/DeepResearch.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/ExecuteCode/ExecuteCode.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/ExecuteWorkflow/ExecuteWorkflow.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/FunctionTools/FunctionTools.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/GenerateCode/GenerateCode.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/InputArguments/InputArguments.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/Marketing/Marketing.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/StudentTeacher/StudentTeacher.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Declarative/ToolApproval/ToolApproval.csproj" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/Declarative/Examples/">
     <File Path="../workflow-samples/CustomerSupport.yaml" />
     <File Path="../workflow-samples/DeepResearch.yaml" />
     <File Path="../workflow-samples/Marketing.yaml" />
@@ -195,114 +214,59 @@
     <File Path="../workflow-samples/README.md" />
     <File Path="../workflow-samples/wttr.json" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/SharedStates/">
-    <Project Path="samples/03-workflows/SharedStates/SharedStates.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/SharedStates/">
+    <Project Path="samples/GettingStarted/Workflows/SharedStates/SharedStates.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Loop/">
-    <Project Path="samples/03-workflows/Loop/Loop.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/Loop/">
+    <Project Path="samples/GettingStarted/Workflows/Loop/Loop.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Agents/">
-    <Project Path="samples/03-workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj" />
-    <Project Path="samples/03-workflows/Agents/FoundryAgent/FoundryAgent.csproj" />
-    <Project Path="samples/03-workflows/Agents/GroupChatToolApproval/GroupChatToolApproval.csproj" />
-    <Project Path="samples/03-workflows/Agents/WorkflowAsAnAgent/WorkflowAsAnAgent.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/Agents/">
+    <Project Path="samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Agents/FoundryAgent/FoundryAgent.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/WorkflowAsAnAgent.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Checkpoint/">
-    <Project Path="samples/03-workflows/Checkpoint/CheckpointAndRehydrate/CheckpointAndRehydrate.csproj" />
-    <Project Path="samples/03-workflows/Checkpoint/CheckpointAndResume/CheckpointAndResume.csproj" />
-    <Project Path="samples/03-workflows/Checkpoint/CheckpointWithHumanInTheLoop/CheckpointWithHumanInTheLoop.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/Checkpoint/">
+    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointAndRehydrate/CheckpointAndRehydrate.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointAndResume/CheckpointAndResume.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Checkpoint/CheckpointWithHumanInTheLoop/CheckpointWithHumanInTheLoop.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/HumanInTheLoop/">
-    <Project Path="samples/03-workflows/HumanInTheLoop/HumanInTheLoopBasic/HumanInTheLoopBasic.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/HumanInTheLoop/">
+    <Project Path="samples/GettingStarted/Workflows/HumanInTheLoop/HumanInTheLoopBasic/HumanInTheLoopBasic.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Observability/">
-    <Project Path="samples/03-workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
-    <Project Path="samples/03-workflows/Observability/AspireDashboard/AspireDashboard.csproj" />
-    <Project Path="samples/03-workflows/Observability/WorkflowAsAnAgent/WorkflowAsAnAgentObservability.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/Observability/">
+    <Project Path="samples/GettingStarted/Workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Observability/AspireDashboard/AspireDashboard.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Observability/WorkflowAsAnAgent/WorkflowAsAnAgentObservability.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/Visualization/">
-    <Project Path="samples/03-workflows/Visualization/Visualization.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/Visualization/">
+    <Project Path="samples/GettingStarted/Workflows/Visualization/Visualization.csproj" />
   </Folder>
-  <Folder Name="/Samples/03-workflows/_StartHere/">
-    <Project Path="samples/03-workflows/_StartHere/01_Streaming/01_Streaming.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/02_AgentsInWorkflows/02_AgentsInWorkflows.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/03_AgentWorkflowPatterns/03_AgentWorkflowPatterns.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/04_MultiModelService/04_MultiModelService.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/05_SubWorkflows/05_SubWorkflows.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/06_MixedWorkflowAgentsAndExecutors/06_MixedWorkflowAgentsAndExecutors.csproj" />
-    <Project Path="samples/03-workflows/_StartHere/07_WriterCriticWorkflow/07_WriterCriticWorkflow.csproj" />
+  <Folder Name="/Samples/GettingStarted/Workflows/_Foundational/">
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/01_ExecutorsAndEdges/01_ExecutorsAndEdges.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/02_Streaming/02_Streaming.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/03_AgentsInWorkflows/03_AgentsInWorkflows.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/04_AgentWorkflowPatterns/04_AgentWorkflowPatterns.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/05_MultiModelService/05_MultiModelService.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/06_SubWorkflows/06_SubWorkflows.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/07_MixedWorkflowAgentsAndExecutors/07_MixedWorkflowAgentsAndExecutors.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/08_WriterCriticWorkflow.csproj" />
   </Folder>
-  <Folder Name="/Samples/04-hosting/" />
-  <Folder Name="/Samples/04-hosting/DurableAgents/" />
-  <Folder Name="/Samples/04-hosting/DurableAgents/AzureFunctions/">
-    <File Path="samples/04-hosting/DurableAgents/AzureFunctions/.editorconfig" />
-    <File Path="samples/04-hosting/DurableAgents/AzureFunctions/README.md" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/01_SingleAgent/01_SingleAgent.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/06_LongRunningTools/06_LongRunningTools.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/07_AgentAsMcpTool/07_AgentAsMcpTool.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/AzureFunctions/08_ReliableStreaming/08_ReliableStreaming.csproj" />
+  <Folder Name="/Samples/HostedAgents/">
+    <Project Path="samples/HostedAgents/AgentsInWorkflows/AgentsInWorkflows.csproj" />
+    <Project Path="samples/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj" />
+    <Project Path="samples/HostedAgents/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
   </Folder>
-  <Folder Name="/Samples/04-hosting/DurableAgents/ConsoleApps/">
-    <File Path="samples/04-hosting/DurableAgents/ConsoleApps/README.md" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/01_SingleAgent/01_SingleAgent.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/02_AgentOrchestration_Chaining/02_AgentOrchestration_Chaining.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/03_AgentOrchestration_Concurrency/03_AgentOrchestration_Concurrency.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/04_AgentOrchestration_Conditionals/04_AgentOrchestration_Conditionals.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/05_AgentOrchestration_HITL/05_AgentOrchestration_HITL.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/06_LongRunningTools/06_LongRunningTools.csproj" />
-    <Project Path="samples/04-hosting/DurableAgents/ConsoleApps/07_ReliableStreaming/07_ReliableStreaming.csproj" />
-  </Folder>
-  <Folder Name="/Samples/04-hosting/A2A/">
-    <File Path="samples/04-hosting/A2A/README.md" />
-    <Project Path="samples/04-hosting/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
-    <Project Path="samples/04-hosting/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
-  </Folder>  
-  <Folder Name="/Samples/05-end-to-end/">
-    <Project Path="samples/05-end-to-end/AgentWithPurview/AgentWithPurview.csproj" />
-    <Project Path="samples/05-end-to-end/M365Agent/M365Agent.csproj" />
-  </Folder>
-  <Folder Name="/Samples/05-end-to-end/A2AClientServer/">
-    <File Path="samples/05-end-to-end/A2AClientServer/README.md" />
-    <Project Path="samples/05-end-to-end/A2AClientServer/A2AClient/A2AClient.csproj" />
-    <Project Path="samples/05-end-to-end/A2AClientServer/A2AServer/A2AServer.csproj" />
-  </Folder>
-  <Folder Name="/Samples/05-end-to-end/AgentWebChat/">
-    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.AgentHost/AgentWebChat.AgentHost.csproj" />
-    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.AppHost/AgentWebChat.AppHost.csproj" />
-    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.ServiceDefaults/AgentWebChat.ServiceDefaults.csproj" />
-    <Project Path="samples/05-end-to-end/AgentWebChat/AgentWebChat.Web/AgentWebChat.Web.csproj" />
-  </Folder>
-  <Folder Name="/Samples/05-end-to-end/AGUIClientServer/">
-    <File Path="samples/05-end-to-end/AGUIClientServer/README.md" />
-    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIClient/AGUIClient.csproj" />
-    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIDojoServer/AGUIDojoServer.csproj" />
-    <Project Path="samples/05-end-to-end/AGUIClientServer/AGUIServer/AGUIServer.csproj" />
-  </Folder>
-  <Folder Name="/Samples/05-end-to-end/HostedAgents/">
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentsInWorkflows/AgentsInWorkflows.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj" />
-    <Project Path="samples/05-end-to-end/HostedAgents/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
-  </Folder>
-  <Folder Name="/Samples/05-end-to-end/AspNetAgentAuthorization/">
-    <File Path="samples/05-end-to-end/AspNetAgentAuthorization/docker-compose.yml" />
-    <File Path="samples/05-end-to-end/AspNetAgentAuthorization/README.md" />
-    <Project Path="samples/05-end-to-end/AspNetAgentAuthorization/Service/Service.csproj" />
-    <Project Path="samples/05-end-to-end/AspNetAgentAuthorization/RazorWebClient/RazorWebClient.csproj" />
+  <Folder Name="/Samples/M365Agent/">
+    <Project Path="samples/M365Agent/M365Agent.csproj" />
   </Folder>
   <Folder Name="/Solution Items/">
     <File Path=".editorconfig" />
     <File Path=".gitignore" />
-    <File Path="AGENTS.md" />
     <File Path="Directory.Build.props" />
     <File Path="Directory.Build.targets" />
     <File Path="Directory.Packages.props" />
     <File Path="global.json" />
     <File Path="nuget.config" />
-    <File Path="README.md" />
   </Folder>
   <Folder Name="/Solution Items/.github/" />
   <Folder Name="/Solution Items/.github/upgrades/" />
@@ -329,15 +293,6 @@
     <File Path="../docs/decisions/0007-agent-filtering-middleware.md" />
     <File Path="../docs/decisions/0008-python-subpackages.md" />
     <File Path="../docs/decisions/0009-support-long-running-operations.md" />
-    <File Path="../docs/decisions/0010-ag-ui-support.md" />
-    <File Path="../docs/decisions/0011-create-get-agent-api.md" />
-    <File Path="../docs/decisions/0012-python-typeddict-options.md" />
-    <File Path="../docs/decisions/0013-python-get-response-simplification.md" />
-    <File Path="../docs/decisions/0014-feature-collections.md" />
-    <File Path="../docs/decisions/0015-agent-run-context.md" />
-    <File Path="../docs/decisions/0016-python-context-middleware.md" />
-    <File Path="../docs/decisions/0017-agent-additional-properties.md" />
-    <File Path="../docs/decisions/0018-agentthread-serialization.md" />
     <File Path="../docs/decisions/adr-short-template.md" />
     <File Path="../docs/decisions/adr-template.md" />
     <File Path="../docs/decisions/README.md" />
@@ -402,10 +357,6 @@
     <File Path="src/Shared/Demos/README.md" />
     <File Path="src/Shared/Demos/SampleEnvironment.cs" />
   </Folder>
-  <Folder Name="/Solution Items/src/Shared/DiagnosticIds/">
-    <File Path="src/Shared/DiagnosticIds/DiagnosticsIds.cs" />
-    <File Path="src/Shared/DiagnosticIds/README.md" />
-  </Folder>
   <Folder Name="/Solution Items/src/Shared/IntegrationTests/">
     <File Path="src/Shared/IntegrationTests/AnthropicConfiguration.cs" />
     <File Path="src/Shared/IntegrationTests/AzureAIConfiguration.cs" />
@@ -424,9 +375,6 @@
     <File Path="src/Shared/Throw/README.md" />
     <File Path="src/Shared/Throw/Throw.cs" />
   </Folder>
-  <Folder Name="/Solution Items/src/Shared/StructuredOutput/">
-    <File Path="src/Shared/StructuredOutput/StructuredOutputSchemaUtilities.cs" />
-  </Folder>
   <Folder Name="/Solution Items/tests/">
     <File Path="tests/.editorconfig" />
     <File Path="tests/Directory.Build.props" />
@@ -443,8 +391,6 @@
     <Project Path="src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj" />
     <Project Path="src/Microsoft.Agents.AI.DevUI/Microsoft.Agents.AI.DevUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.FoundryMemory/Microsoft.Agents.AI.FoundryMemory.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
@@ -455,9 +401,7 @@
     <Project Path="src/Microsoft.Agents.AI.OpenAI/Microsoft.Agents.AI.OpenAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.AzureAI/Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.Mcp/Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Workflows.Generators/Microsoft.Agents.AI.Workflows.Generators.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
     <Project Path="src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj" />
   </Folder>
@@ -469,8 +413,6 @@
     <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
     <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DurableTask.IntegrationTests/Microsoft.Agents.AI.DurableTask.IntegrationTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.FoundryMemory.IntegrationTests/Microsoft.Agents.AI.FoundryMemory.IntegrationTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests/Microsoft.Agents.AI.GitHub.Copilot.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests/Microsoft.Agents.AI.Hosting.AzureFunctions.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Mem0.IntegrationTests/Microsoft.Agents.AI.Mem0.IntegrationTests.csproj" />
@@ -490,8 +432,6 @@
     <Project Path="tests/Microsoft.Agents.AI.Declarative.UnitTests/Microsoft.Agents.AI.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DevUI.UnitTests/Microsoft.Agents.AI.DevUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.DurableTask.UnitTests/Microsoft.Agents.AI.DurableTask.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.FoundryMemory.UnitTests/Microsoft.Agents.AI.FoundryMemory.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests/Microsoft.Agents.AI.GitHub.Copilot.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Microsoft.Agents.AI.Hosting.A2A.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests/Microsoft.Agents.AI.Hosting.AzureFunctions.UnitTests.csproj" />
@@ -501,9 +441,7 @@
     <Project Path="tests/Microsoft.Agents.AI.OpenAI.UnitTests/Microsoft.Agents.AI.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Purview.UnitTests/Microsoft.Agents.AI.Purview.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.UnitTests/Microsoft.Agents.AI.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.Workflows.Generators.UnitTests/Microsoft.Agents.AI.Workflows.Generators.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj" />
   </Folder>
 </Solution>

dotnet/agent-framework-release.slnf

@@ -6,7 +6,6 @@
       "src\\Microsoft.Agents.AI.Abstractions\\Microsoft.Agents.AI.Abstractions.csproj",
       "src\\Microsoft.Agents.AI.AGUI\\Microsoft.Agents.AI.AGUI.csproj",
       "src\\Microsoft.Agents.AI.Anthropic\\Microsoft.Agents.AI.Anthropic.csproj",
-      "src\\Microsoft.Agents.AI.GitHub.Copilot\\Microsoft.Agents.AI.GitHub.Copilot.csproj",
       "src\\Microsoft.Agents.AI.AzureAI.Persistent\\Microsoft.Agents.AI.AzureAI.Persistent.csproj",
       "src\\Microsoft.Agents.AI.AzureAI\\Microsoft.Agents.AI.AzureAI.csproj",
       "src\\Microsoft.Agents.AI.CopilotStudio\\Microsoft.Agents.AI.CopilotStudio.csproj",
@@ -25,7 +24,6 @@
       "src\\Microsoft.Agents.AI.Purview\\Microsoft.Agents.AI.Purview.csproj",
       "src\\Microsoft.Agents.AI.Workflows.Declarative.AzureAI\\Microsoft.Agents.AI.Workflows.Declarative.AzureAI.csproj",
       "src\\Microsoft.Agents.AI.Workflows.Declarative\\Microsoft.Agents.AI.Workflows.Declarative.csproj",
-      "src\\Microsoft.Agents.AI.Workflows.Generators\\Microsoft.Agents.AI.Workflows.Generators.csproj",
       "src\\Microsoft.Agents.AI.Workflows\\Microsoft.Agents.AI.Workflows.csproj",
       "src\\Microsoft.Agents.AI\\Microsoft.Agents.AI.csproj"
     ]

dotnet/eng/MSBuild/Shared.props

@@ -20,10 +20,4 @@
   <ItemGroup Condition="'$(InjectSharedFoundryAgents)' == 'true'">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\Foundry\Agents\*.cs" LinkBase="Shared\Foundry" />
   </ItemGroup>
-  <ItemGroup Condition="'$(InjectSharedStructuredOutput)' == 'true'">
-    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\StructuredOutput\*.cs" LinkBase="Shared\StructuredOutput" />
-  </ItemGroup>
-  <ItemGroup Condition="'$(InjectSharedDiagnosticIds)' == 'true'">
-    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\DiagnosticIds\*.cs" LinkBase="Shared\DiagnosticIds" />
-  </ItemGroup>
 </Project>

dotnet/nuget.config

@@ -3,10 +3,14 @@
   <packageSources>
     <clear />
     <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+    <add key="LocalNugetSource" value="C:\LocalNugetSource" />
   </packageSources>
   <packageSourceMapping>
     <packageSource key="nuget.org">
       <package pattern="*" />
     </packageSource>
+    <packageSource key="LocalNugetSource">
+      <package pattern="*" />
+    </packageSource>
   </packageSourceMapping>
 </configuration>

dotnet/nuget/nuget-package.props

@@ -2,11 +2,9 @@
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
     <VersionPrefix>1.0.0</VersionPrefix>
-    <RCNumber>3</RCNumber>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' == 'true'">$(VersionPrefix)-rc$(RCNumber)</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260304.1</PackageVersion>
-    <PackageVersion Condition="'$(IsReleaseCandidate)' != 'true' AND '$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260304.1</PackageVersion>
-    <GitTag>1.0.0-rc3</GitTag>
+    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).260108.1</PackageVersion>
+    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.260108.1</PackageVersion>
+    <GitTag>1.0.0-preview.260108.1</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

dotnet/samples/01-get-started/04_memory/Program.cs

@@ -1,162 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to add a basic custom memory component to an agent.
-// The memory component subscribes to all messages added to the conversation and
-// extracts the user's name and age if provided.
-// The component adds a prompt to ask for this information if it is not already known
-// and provides it to the model before each invocation if known.
-
-using System.Text;
-using System.Text.Json;
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using OpenAI.Chat;
-using SampleApp;
-
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-ChatClient chatClient = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-    .GetChatClient(deploymentName);
-
-// Create the agent and provide a factory to add our custom memory component to
-// all sessions created by the agent. Here each new memory component will have its own
-// user info object, so each session will have its own memory.
-// In real world applications/services, where the user info would be persisted in a database,
-// and preferably shared between multiple sessions used by the same user, ensure that the
-// factory reads the user id from the current context and scopes the memory component
-// and its storage to that user id.
-AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
-{
-    ChatOptions = new() { Instructions = "You are a friendly assistant. Always address the user by their name." },
-    AIContextProviders = [new UserInfoMemory(chatClient.AsIChatClient())]
-});
-
-// Create a new session for the conversation.
-AgentSession session = await agent.CreateSessionAsync();
-
-Console.WriteLine(">> Use session with blank memory\n");
-
-// Invoke the agent and output the text result.
-Console.WriteLine(await agent.RunAsync("Hello, what is the square root of 9?", session));
-Console.WriteLine(await agent.RunAsync("My name is Ruaidhrí", session));
-Console.WriteLine(await agent.RunAsync("I am 20 years old", session));
-
-// We can serialize the session. The serialized state will include the state of the memory component.
-JsonElement sesionElement = await agent.SerializeSessionAsync(session);
-
-Console.WriteLine("\n>> Use deserialized session with previously created memories\n");
-
-// Later we can deserialize the session and continue the conversation with the previous memory component state.
-var deserializedSession = await agent.DeserializeSessionAsync(sesionElement);
-Console.WriteLine(await agent.RunAsync("What is my name and age?", deserializedSession));
-
-Console.WriteLine("\n>> Read memories using memory component\n");
-
-// It's possible to access the memory component via the agent's GetService method.
-var userInfo = agent.GetService<UserInfoMemory>()?.GetUserInfo(deserializedSession);
-
-// Output the user info that was captured by the memory component.
-Console.WriteLine($"MEMORY - User Name: {userInfo?.UserName}");
-Console.WriteLine($"MEMORY - User Age: {userInfo?.UserAge}");
-
-Console.WriteLine("\n>> Use new session with previously created memories\n");
-
-// It is also possible to set the memories using a memory component on an individual session.
-// This is useful if we want to start a new session, but have it share the same memories as a previous session.
-var newSession = await agent.CreateSessionAsync();
-if (userInfo is not null && agent.GetService<UserInfoMemory>() is UserInfoMemory newSessionMemory)
-{
-    newSessionMemory.SetUserInfo(newSession, userInfo);
-}
-
-// Invoke the agent and output the text result.
-// This time the agent should remember the user's name and use it in the response.
-Console.WriteLine(await agent.RunAsync("What is my name and age?", newSession));
-
-namespace SampleApp
-{
-    /// <summary>
-    /// Sample memory component that can remember a user's name and age.
-    /// </summary>
-    internal sealed class UserInfoMemory : AIContextProvider
-    {
-        private readonly ProviderSessionState<UserInfo> _sessionState;
-        private IReadOnlyList<string>? _stateKeys;
-        private readonly IChatClient _chatClient;
-
-        public UserInfoMemory(IChatClient chatClient, Func<AgentSession?, UserInfo>? stateInitializer = null)
-        {
-            this._sessionState = new ProviderSessionState<UserInfo>(
-                stateInitializer ?? (_ => new UserInfo()),
-                this.GetType().Name);
-            this._chatClient = chatClient;
-        }
-
-        public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey];
-
-        public UserInfo GetUserInfo(AgentSession session)
-            => this._sessionState.GetOrInitializeState(session);
-
-        public void SetUserInfo(AgentSession session, UserInfo userInfo)
-            => this._sessionState.SaveState(session, userInfo);
-
-        protected override async ValueTask StoreAIContextAsync(InvokedContext context, CancellationToken cancellationToken = default)
-        {
-            var userInfo = this._sessionState.GetOrInitializeState(context.Session);
-
-            // Try and extract the user name and age from the message if we don't have it already and it's a user message.
-            if ((userInfo.UserName is null || userInfo.UserAge is null) && context.RequestMessages.Any(x => x.Role == ChatRole.User))
-            {
-                var result = await this._chatClient.GetResponseAsync<UserInfo>(
-                    context.RequestMessages,
-                    new ChatOptions()
-                    {
-                        Instructions = "Extract the user's name and age from the message if present. If not present return nulls."
-                    },
-                    cancellationToken: cancellationToken);
-
-                userInfo.UserName ??= result.Result.UserName;
-                userInfo.UserAge ??= result.Result.UserAge;
-            }
-
-            this._sessionState.SaveState(context.Session, userInfo);
-        }
-
-        protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
-        {
-            var userInfo = this._sessionState.GetOrInitializeState(context.Session);
-
-            StringBuilder instructions = new();
-
-            // If we don't already know the user's name and age, add instructions to ask for them, otherwise just provide what we have to the context.
-            instructions
-                .AppendLine(
-                    userInfo.UserName is null ?
-                        "Ask the user for their name and politely decline to answer any questions until they provide it." :
-                        $"The user's name is {userInfo.UserName}.")
-                .AppendLine(
-                    userInfo.UserAge is null ?
-                        "Ask the user for their age and politely decline to answer any questions until they provide it." :
-                        $"The user's age is {userInfo.UserAge}.");
-
-            return new ValueTask<AIContext>(new AIContext
-            {
-                Instructions = instructions.ToString()
-            });
-        }
-    }
-
-    internal sealed class UserInfo
-    {
-        public string? UserName { get; set; }
-        public int? UserAge { get; set; }
-    }
-}

dotnet/samples/01-get-started/05_first_workflow/05_first_workflow.csproj

@@ -1,14 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
-  </ItemGroup>
-
-</Project>

dotnet/samples/01-get-started/06_host_your_agent/06_host_your_agent.csproj

@@ -1,31 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-    <!-- The Functions build tools don't like namespaces that start with a number -->
-    <AssemblyName>HostedAgent</AssemblyName>
-    <RootNamespace>HostedAgent</RootNamespace>
-  </PropertyGroup>
-  <ItemGroup>
-    <FrameworkReference Include="Microsoft.AspNetCore.App" />
-  </ItemGroup>
-  <!-- Azure Functions packages -->
-  <ItemGroup>
-    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
-    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
-  </ItemGroup>
-  <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
-    <PackageReference Include="Azure.Identity" />
-  </ItemGroup>
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
-  </ItemGroup>
-</Project>

dotnet/samples/01-get-started/06_host_your_agent/Program.cs

@@ -1,45 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to host an AI agent with Azure Functions (DurableAgents).
-//
-// Prerequisites:
-//   - Azure Functions Core Tools
-//   - Azure OpenAI resource
-//
-// Environment variables:
-//   AZURE_OPENAI_ENDPOINT
-//   AZURE_OPENAI_DEPLOYMENT_NAME (defaults to "gpt-4o-mini")
-//
-// Run with: func start
-// Then call: POST http://localhost:7071/api/agents/HostedAgent/run
-
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Hosting.AzureFunctions;
-using Microsoft.Azure.Functions.Worker.Builder;
-using Microsoft.Extensions.Hosting;
-using OpenAI.Chat;
-
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
-    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-// Set up an AI agent following the standard Microsoft Agent Framework pattern.
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent(
-        instructions: "You are a helpful assistant hosted in Azure Functions.",
-        name: "HostedAgent");
-
-// Configure the function app to host the AI agent.
-// This will automatically generate HTTP API endpoints for the agent.
-using IHost app = FunctionsApplication
-    .CreateBuilder(args)
-    .ConfigureFunctionsWebApplication()
-    .ConfigureDurableAgents(options => options.AddAIAgent(agent, timeToLive: TimeSpan.FromHours(1)))
-    .Build();
-app.Run();

dotnet/samples/02-agents/AgentProviders/Agent_With_Anthropic/Program.cs

@@ -1,32 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to create and use an AI agent with Anthropic as the backend.
-
-using Anthropic;
-using Anthropic.Foundry;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-
-string deploymentName = Environment.GetEnvironmentVariable("ANTHROPIC_CHAT_MODEL_NAME") ?? "claude-haiku-4-5";
-
-// The resource is the subdomain name / first name coming before '.services.ai.azure.com' in the endpoint Uri
-// ie: https://(resource name).services.ai.azure.com/anthropic/v1/chat/completions
-string? resource = Environment.GetEnvironmentVariable("ANTHROPIC_RESOURCE");
-string? apiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY");
-
-const string JokerInstructions = "You are good at telling jokes.";
-const string JokerName = "JokerAgent";
-
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-using AnthropicClient client = (resource is null)
-    ? new AnthropicClient() { ApiKey = apiKey ?? throw new InvalidOperationException("ANTHROPIC_API_KEY is required when no ANTHROPIC_RESOURCE is provided") }  // If no resource is provided, use Anthropic public API
-    : (apiKey is not null)
-        ? new AnthropicFoundryClient(new AnthropicFoundryApiKeyCredentials(apiKey, resource)) // If an apiKey is provided, use Foundry with ApiKey authentication
-        : new AnthropicFoundryClient(new AnthropicFoundryIdentityTokenCredentials(new DefaultAzureCredential(), resource, ["https://ai.azure.com/.default"])); // Otherwise, use Foundry with Azure TokenCredential authentication
-
-AIAgent agent = client.AsAIAgent(model: deploymentName, instructions: JokerInstructions, name: JokerName);
-
-// Invoke the agent and output the text result.
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

dotnet/samples/02-agents/AgentProviders/Agent_With_AzureOpenAIResponses/Program.cs

@@ -1,37 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to create and use a simple AI agent with Azure OpenAI Responses as the backend.
-
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using OpenAI.Responses;
-
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-     .GetResponsesClient(deploymentName)
-     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
-
-// Invoke the agent and output the text result.
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
-
-// Create a responses based agent with "store"=false.
-// This means that chat history is managed locally by Agent Framework
-// instead of being stored in the service (default).
-AIAgent agentStoreFalse = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-     .GetResponsesClient(deploymentName)
-     .AsIChatClientWithStoredOutputDisabled()
-     .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
-
-// Invoke the agent and output the text result.
-Console.WriteLine(await agentStoreFalse.RunAsync("Tell me a joke about a pirate."));

dotnet/samples/02-agents/AgentProviders/Agent_With_CustomImplementation/Program.cs

@@ -1,152 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows all the required steps to create a fully custom agent implementation.
-// In this case the agent doesn't use AI at all, and simply parrots back the user input in upper case.
-// You can however, build a fully custom agent that uses AI in any way you want.
-
-using System.Runtime.CompilerServices;
-using System.Text.Json;
-using System.Text.Json.Serialization;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using SampleApp;
-
-AIAgent agent = new UpperCaseParrotAgent();
-
-// Invoke the agent and output the text result.
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));
-
-// Invoke the agent with streaming support.
-await foreach (var update in agent.RunStreamingAsync("Tell me a joke about a pirate."))
-{
-    Console.WriteLine(update);
-}
-
-namespace SampleApp
-{
-    // Custom agent that parrot's the user input back in upper case.
-    internal sealed class UpperCaseParrotAgent : AIAgent
-    {
-        public override string? Name => "UpperCaseParrotAgent";
-
-        public readonly ChatHistoryProvider ChatHistoryProvider = new InMemoryChatHistoryProvider();
-
-        protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
-            => new(new CustomAgentSession());
-
-        protected override ValueTask<JsonElement> SerializeSessionCoreAsync(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
-        {
-            if (session is not CustomAgentSession typedSession)
-            {
-                throw new ArgumentException($"The provided session is not of type {nameof(CustomAgentSession)}.", nameof(session));
-            }
-
-            return new(JsonSerializer.SerializeToElement(typedSession, jsonSerializerOptions));
-        }
-
-        protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(JsonElement serializedState, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
-            => new(serializedState.Deserialize<CustomAgentSession>(jsonSerializerOptions)!);
-
-        protected override async Task<AgentResponse> RunCoreAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, CancellationToken cancellationToken = default)
-        {
-            // Create a session if the user didn't supply one.
-            session ??= await this.CreateSessionAsync(cancellationToken);
-
-            if (session is not CustomAgentSession typedSession)
-            {
-                throw new ArgumentException($"The provided session is not of type {nameof(CustomAgentSession)}.", nameof(session));
-            }
-
-            // Get existing messages from the store
-            var invokingContext = new ChatHistoryProvider.InvokingContext(this, session, messages);
-            var userAndChatHistoryMessages = await this.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
-
-            // Clone the input messages and turn them into response messages with upper case text.
-            List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();
-
-            // Notify the session of the input and output messages.
-            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, userAndChatHistoryMessages, responseMessages);
-            await this.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
-
-            return new AgentResponse
-            {
-                AgentId = this.Id,
-                ResponseId = Guid.NewGuid().ToString("N"),
-                Messages = responseMessages
-            };
-        }
-
-        protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(IEnumerable<ChatMessage> messages, AgentSession? session = null, AgentRunOptions? options = null, [EnumeratorCancellation] CancellationToken cancellationToken = default)
-        {
-            // Create a session if the user didn't supply one.
-            session ??= await this.CreateSessionAsync(cancellationToken);
-
-            if (session is not CustomAgentSession typedSession)
-            {
-                throw new ArgumentException($"The provided session is not of type {nameof(CustomAgentSession)}.", nameof(session));
-            }
-
-            // Get existing messages from the store
-            var invokingContext = new ChatHistoryProvider.InvokingContext(this, session, messages);
-            var userAndChatHistoryMessages = await this.ChatHistoryProvider.InvokingAsync(invokingContext, cancellationToken);
-
-            // Clone the input messages and turn them into response messages with upper case text.
-            List<ChatMessage> responseMessages = CloneAndToUpperCase(messages, this.Name).ToList();
-
-            // Notify the session of the input and output messages.
-            var invokedContext = new ChatHistoryProvider.InvokedContext(this, session, userAndChatHistoryMessages, responseMessages);
-            await this.ChatHistoryProvider.InvokedAsync(invokedContext, cancellationToken);
-
-            foreach (var message in responseMessages)
-            {
-                yield return new AgentResponseUpdate
-                {
-                    AgentId = this.Id,
-                    AuthorName = message.AuthorName,
-                    Role = ChatRole.Assistant,
-                    Contents = message.Contents,
-                    ResponseId = Guid.NewGuid().ToString("N"),
-                    MessageId = Guid.NewGuid().ToString("N")
-                };
-            }
-        }
-
-        private static IEnumerable<ChatMessage> CloneAndToUpperCase(IEnumerable<ChatMessage> messages, string? agentName) => messages.Select(x =>
-            {
-                // Clone the message and update its author to be the agent.
-                var messageClone = x.Clone();
-                messageClone.Role = ChatRole.Assistant;
-                messageClone.MessageId = Guid.NewGuid().ToString("N");
-                messageClone.AuthorName = agentName;
-
-                // Clone and convert any text content to upper case.
-                messageClone.Contents = x.Contents.Select(c => c switch
-                {
-                    TextContent tc => new TextContent(tc.Text.ToUpperInvariant())
-                    {
-                        AdditionalProperties = tc.AdditionalProperties,
-                        Annotations = tc.Annotations,
-                        RawRepresentation = tc.RawRepresentation
-                    },
-                    _ => c
-                }).ToList();
-
-                return messageClone;
-            });
-
-        /// <summary>
-        /// A session type for our custom agent that only supports in memory storage of messages.
-        /// </summary>
-        internal sealed class CustomAgentSession : AgentSession
-        {
-            internal CustomAgentSession()
-            {
-            }
-
-            [JsonConstructor]
-            internal CustomAgentSession(AgentSessionStateBag stateBag) : base(stateBag)
-            {
-            }
-        }
-    }
-}

dotnet/samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/Program.cs

@@ -1,51 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to create a GitHub Copilot agent with shell command permissions.
-
-using GitHub.Copilot.SDK;
-using Microsoft.Agents.AI;
-
-// Permission handler that prompts the user for approval
-static Task<PermissionRequestResult> PromptPermission(PermissionRequest request, PermissionInvocation invocation)
-{
-    Console.WriteLine($"\n[Permission Request: {request.Kind}]");
-    Console.Write("Approve? (y/n): ");
-
-    string? input = Console.ReadLine()?.Trim().ToUpperInvariant();
-    string kind = input is "Y" or "YES" ? "approved" : "denied-interactively-by-user";
-
-    return Task.FromResult(new PermissionRequestResult { Kind = kind });
-}
-
-// Create and start a Copilot client
-await using CopilotClient copilotClient = new();
-await copilotClient.StartAsync();
-
-// Create an agent with a session config that enables permission handling
-SessionConfig sessionConfig = new()
-{
-    OnPermissionRequest = PromptPermission,
-};
-
-AIAgent agent = copilotClient.AsAIAgent(sessionConfig, ownsClient: true);
-
-// Toggle between streaming and non-streaming modes
-bool useStreaming = true;
-
-string prompt = "List all files in the current directory";
-Console.WriteLine($"User: {prompt}\n");
-
-if (useStreaming)
-{
-    await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(prompt))
-    {
-        Console.Write(update);
-    }
-
-    Console.WriteLine();
-}
-else
-{
-    AgentResponse response = await agent.RunAsync(prompt);
-    Console.WriteLine(response);
-}

dotnet/samples/02-agents/AgentProviders/Agent_With_GitHubCopilot/README.md

@@ -1,76 +0,0 @@
-# Prerequisites
-
-> **⚠️ WARNING: Container Recommendation**
-> 
-> GitHub Copilot can execute tools and commands that may interact with your system. For safety, it is strongly recommended to run this sample in a containerized environment (e.g., Docker, Dev Container) to avoid unintended consequences to your machine.
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 10 SDK or later
-- GitHub Copilot CLI installed and available in your PATH (or provide a custom path)
-
-## Setting up GitHub Copilot CLI
-
-To use this sample, you need to have the GitHub Copilot CLI installed. You can install it by following the instructions at:
-https://github.com/github/copilot-sdk
-
-Once installed, ensure the `copilot` command is available in your PATH, or configure a custom path using `CopilotClientOptions`.
-
-## Running the Sample
-
-No additional environment variables are required if using default configuration. The sample will:
-
-1. Create a GitHub Copilot client with default options
-2. Create an AI agent using the Copilot SDK
-3. Send a message to the agent
-4. Display the response
-
-Run the sample:
-
-```powershell
-dotnet run
-```
-
-## Advanced Usage
-
-You can customize the agent by providing additional configuration:
-
-```csharp
-using GitHub.Copilot.SDK;
-using Microsoft.Agents.AI;
-
-// Create and start a Copilot client
-await using CopilotClient copilotClient = new();
-await copilotClient.StartAsync();
-
-// Create session configuration with specific model
-SessionConfig sessionConfig = new()
-{
-    Model = "claude-opus-4.5",
-    Streaming = false
-};
-
-// Create an agent with custom configuration using the extension method
-AIAgent agent = copilotClient.AsAIAgent(
-    sessionConfig,
-    ownsClient: true,
-    id: "my-copilot-agent",
-    name: "My Copilot Assistant",
-    description: "A helpful AI assistant powered by GitHub Copilot"
-);
-
-// Use the agent - ask it to write code for us
-AgentResponse response = await agent.RunAsync("Write a small .NET 10 C# hello world single file application");
-Console.WriteLine(response);
-```
-
-## Streaming Responses
-
-To get streaming responses:
-
-```csharp
-await foreach (AgentResponseUpdate update in agent.RunStreamingAsync("Write a C# function to calculate Fibonacci numbers"))
-{
-    Console.Write(update.Text);
-}
-```

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Agent_Step01_BasicSkills.csproj

@@ -1,28 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <NoWarn>$(NoWarn);MAAI001</NoWarn>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
-    <PackageReference Include="Azure.Identity" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
-  </ItemGroup>
-
-  <!-- Copy skills directory to output -->
-  <ItemGroup>
-    <None Include="skills\**\*.*">
-      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-    </None>
-  </ItemGroup>
-
-</Project>

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/Program.cs

@@ -1,49 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to use Agent Skills with a ChatClientAgent.
-// Agent Skills are modular packages of instructions and resources that extend an agent's capabilities.
-// Skills follow the progressive disclosure pattern: advertise -> load -> read resources.
-//
-// This sample includes the expense-report skill:
-//   - Policy-based expense filing with references and assets
-
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using OpenAI.Responses;
-
-// --- Configuration ---
-string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
-    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-// --- Skills Provider ---
-// Discovers skills from the 'skills' directory and makes them available to the agent
-var skillsProvider = new FileAgentSkillsProvider(skillPath: Path.Combine(AppContext.BaseDirectory, "skills"));
-
-// --- Agent Setup ---
-AIAgent agent = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
-    .GetResponsesClient(deploymentName)
-    .AsAIAgent(new ChatClientAgentOptions
-    {
-        Name = "SkillsAgent",
-        ChatOptions = new()
-        {
-            Instructions = "You are a helpful assistant.",
-        },
-        AIContextProviders = [skillsProvider],
-    });
-
-// --- Example 1: Expense policy question (loads FAQ resource) ---
-Console.WriteLine("Example 1: Checking expense policy FAQ");
-Console.WriteLine("---------------------------------------");
-AgentResponse response1 = await agent.RunAsync("Are tips reimbursable? I left a 25% tip on a taxi ride and want to know if that's covered.");
-Console.WriteLine($"Agent: {response1.Text}\n");
-
-// --- Example 2: Filing an expense report (multi-turn with template asset) ---
-Console.WriteLine("Example 2: Filing an expense report");
-Console.WriteLine("---------------------------------------");
-AgentSession session = await agent.CreateSessionAsync();
-AgentResponse response2 = await agent.RunAsync("I had 3 client dinners and a $1,200 flight last week. Return a draft expense report and ask about any missing details.",
-    session);
-Console.WriteLine($"Agent: {response2.Text}\n");

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/README.md

@@ -1,63 +0,0 @@
-# Agent Skills Sample
-
-This sample demonstrates how to use **Agent Skills** with a `ChatClientAgent` in the Microsoft Agent Framework.
-
-## What are Agent Skills?
-
-Agent Skills are modular packages of instructions and resources that enable AI agents to perform specialized tasks. They follow the [Agent Skills specification](https://agentskills.io/) and implement the progressive disclosure pattern:
-
-1. **Advertise**: Skills are advertised with name + description (~100 tokens per skill)
-2. **Load**: Full instructions are loaded on-demand via `load_skill` tool
-3. **Resources**: References and other files loaded via `read_skill_resource` tool
-
-## Skills Included
-
-### expense-report
-Policy-based expense filing with spending limits, receipt requirements, and approval workflows.
-- `references/POLICY_FAQ.md` — Detailed expense policy Q&A
-- `assets/expense-report-template.md` — Submission template
-
-## Project Structure
-
-```
-Agent_Step01_BasicSkills/
-├── Program.cs
-├── Agent_Step01_BasicSkills.csproj
-└── skills/
-    └── expense-report/
-        ├── SKILL.md
-        ├── references/
-        │   └── POLICY_FAQ.md
-        └── assets/
-            └── expense-report-template.md
-```
-
-## Running the Sample
-
-### Prerequisites
-- .NET 10.0 SDK
-- Azure OpenAI endpoint with a deployed model
-
-### Setup
-1. Set environment variables:
-   ```bash
-   export AZURE_OPENAI_ENDPOINT="https://your-endpoint.openai.azure.com/"
-   export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
-   ```
-
-2. Run the sample:
-   ```bash
-   dotnet run
-   ```
-
-### Examples
-
-The sample runs two examples:
-
-1. **Expense policy FAQ** — Asks about tip reimbursement; the agent loads the expense-report skill and reads the FAQ resource
-2. **Filing an expense report** — Multi-turn conversation to draft an expense report using the template asset
-
-## Learn More
-
-- [Agent Skills Specification](https://agentskills.io/)
-- [Microsoft Agent Framework Documentation](../../../../../docs/)

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/skills/expense-report/SKILL.md

@@ -1,40 +0,0 @@
----
-name: expense-report
-description: File and validate employee expense reports according to Contoso company policy. Use when asked about expense submissions, reimbursement rules, receipt requirements, spending limits, or expense categories.
-metadata:
-  author: contoso-finance
-  version: "2.1"
----
-
-# Expense Report
-
-## Categories and Limits
-
-| Category | Limit | Receipt | Approval |
-|---|---|---|---|
-| Meals — solo | $50/day | >$25 | No |
-| Meals — team/client | $75/person | Always | Manager if >$200 total |
-| Lodging | $250/night | Always | Manager if >3 nights |
-| Ground transport | $100/day | >$15 | No |
-| Airfare | Economy | Always | Manager; VP if >$1,500 |
-| Conference/training | $2,000/event | Always | Manager + L&D |
-| Office supplies | $100 | Yes | No |
-| Software/subscriptions | $50/month | Yes | Manager if >$200/year |
-
-## Filing Process
-
-1. Collect receipts — must show vendor, date, amount, payment method.
-2. Categorize per table above.
-3. Use template: [assets/expense-report-template.md](assets/expense-report-template.md).
-4. For client/team meals: list attendee names and business purpose.
-5. Submit — auto-approved if <$500; manager if $500–$2,000; VP if >$2,000.
-6. Reimbursement: 10 business days via direct deposit.
-
-## Policy Rules
-
-- Submit within 30 days of transaction.
-- Alcohol is never reimbursable.
-- Foreign currency: convert to USD at transaction-date rate; note original currency and amount.
-- Mixed personal/business travel: only business portion reimbursable; provide comparison quotes.
-- Lost receipts (>$25): file Lost Receipt Affidavit from Finance. Max 2 per quarter.
-- For policy questions not covered above, consult the FAQ: [references/POLICY_FAQ.md](references/POLICY_FAQ.md). Answers should be based on what this document and the FAQ state.

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/skills/expense-report/assets/expense-report-template.md

@@ -1,5 +0,0 @@
-# Expense Report Template
-
-| Date | Category | Vendor | Description | Amount (USD) | Original Currency | Original Amount | Attendees | Business Purpose | Receipt Attached |
-|------|----------|--------|-------------|--------------|-------------------|-----------------|-----------|------------------|------------------|
-|      |          |        |             |              |                   |                 |           |                  | Yes or No        |

dotnet/samples/02-agents/AgentSkills/Agent_Step01_BasicSkills/skills/expense-report/references/POLICY_FAQ.md

@@ -1,55 +0,0 @@
-# Expense Policy — Frequently Asked Questions
-
-## Meals
-
-**Q: Can I expense coffee or snacks during the workday?**
-A: Daily coffee/snacks under $10 are not reimbursable (considered personal). Coffee purchased during a client meeting or team working session is reimbursable as a team meal.
-
-**Q: What if a team dinner exceeds the per-person limit?**
-A: The $75/person limit applies as a guideline. Overages up to 20% are accepted with a written justification (e.g., "client dinner at venue chosen by client"). Overages beyond 20% require pre-approval from your VP.
-
-**Q: Do I need to list every attendee?**
-A: Yes. For client meals, list the client's name and company. For team meals, list all employee names. For groups over 10, you may attach a separate attendee list.
-
-## Travel
-
-**Q: Can I book a premium economy or business class flight?**
-A: Economy class is the standard. Premium economy is allowed for flights over 6 hours. Business class requires VP pre-approval and is generally reserved for flights over 10 hours or medical accommodation.
-
-**Q: What about ride-sharing (Uber/Lyft) vs. rental cars?**
-A: Use ride-sharing for trips under 30 miles round-trip. Rent a car for multi-day travel or when ride-sharing would exceed $100/day. Always choose the compact/standard category unless traveling with 3+ people.
-
-**Q: Are tips reimbursable?**
-A: Tips up to 20% are reimbursable for meals, taxi/ride-share, and hotel housekeeping. Tips above 20% require justification.
-
-## Lodging
-
-**Q: What if the $250/night limit isn't enough for the city I'm visiting?**
-A: For high-cost cities (New York, San Francisco, London, Tokyo, Sydney), the limit is automatically increased to $350/night. No additional approval is needed. For other locations where rates are unusually high (e.g., during a major conference), request a per-trip exception from your manager before booking.
-
-**Q: Can I stay with friends/family instead and get a per-diem?**
-A: No. Contoso reimburses actual lodging costs only, not per-diems.
-
-## Subscriptions and Software
-
-**Q: Can I expense a personal productivity tool?**
-A: Software must be directly related to your job function. Tools like IDE licenses, design software, or project management apps are reimbursable. General productivity apps (note-taking, personal calendar) are not, unless your manager confirms a business need in writing.
-
-**Q: What about annual subscriptions?**
-A: Annual subscriptions over $200 require manager approval before purchase. Submit the approval email with your expense report.
-
-## Receipts and Documentation
-
-**Q: My receipt is faded/damaged. What do I do?**
-A: Try to obtain a duplicate from the vendor. If not possible, submit a Lost Receipt Affidavit (available from the Finance SharePoint site). You're limited to 2 affidavits per quarter.
-
-**Q: Do I need a receipt for parking meters or tolls?**
-A: For amounts under $15, no receipt is required — just note the date, location, and amount. For $15 and above, a receipt or bank/credit card statement excerpt is required.
-
-## Approval and Reimbursement
-
-**Q: My manager is on leave. Who approves my report?**
-A: Expense reports can be approved by your skip-level manager or any manager designated as an alternate approver in the expense system.
-
-**Q: Can I submit expenses from a previous quarter?**
-A: The standard 30-day window applies. Expenses older than 30 days require a written explanation and VP approval. Expenses older than 90 days are not reimbursable except in extraordinary circumstances (extended leave, medical emergency) with CFO approval.

dotnet/samples/02-agents/AgentSkills/README.md

@@ -1,7 +0,0 @@
-# AgentSkills Samples
-
-Samples demonstrating Agent Skills capabilities.
-
-| Sample | Description |
-|--------|-------------|
-| [Agent_Step01_BasicSkills](Agent_Step01_BasicSkills/) | Using Agent Skills with a ChatClientAgent, including progressive disclosure and skill resources |

dotnet/samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Agent_Anthropic_Step04_UsingSkills.csproj

@@ -1,15 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFramework>net10.0</TargetFramework>
-
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Anthropic\Microsoft.Agents.AI.Anthropic.csproj" />
-  </ItemGroup>
-
-</Project>

dotnet/samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/Program.cs

@@ -1,127 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to use Anthropic-managed Skills with an AI agent.
-// Skills are pre-built capabilities provided by Anthropic that can be used with the Claude API.
-// This sample shows how to:
-// 1. List available Anthropic-managed skills
-// 2. Use the pptx skill to create PowerPoint presentations
-// 3. Download and save generated files
-
-using Anthropic;
-using Anthropic.Core;
-using Anthropic.Models.Beta;
-using Anthropic.Models.Beta.Files;
-using Anthropic.Models.Beta.Messages;
-using Anthropic.Models.Beta.Skills;
-using Anthropic.Services;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-string apiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY") ?? throw new InvalidOperationException("ANTHROPIC_API_KEY is not set.");
-// Skills require Claude 4.5 models (Sonnet 4.5, Haiku 4.5, or Opus 4.5)
-string model = Environment.GetEnvironmentVariable("ANTHROPIC_CHAT_MODEL_NAME") ?? "claude-sonnet-4-5-20250929";
-
-// Create the Anthropic client
-AnthropicClient anthropicClient = new() { ApiKey = apiKey };
-
-// List available Anthropic-managed skills (optional - API may not be available in all regions)
-Console.WriteLine("Available Anthropic-managed skills:");
-try
-{
-    SkillListPage skills = await anthropicClient.Beta.Skills.List(
-        new SkillListParams { Source = "anthropic", Betas = [AnthropicBeta.Skills2025_10_02] });
-
-    foreach (var skill in skills.Items)
-    {
-        Console.WriteLine($"  {skill.Source}: {skill.ID} (version: {skill.LatestVersion})");
-    }
-}
-catch (Exception ex)
-{
-    Console.WriteLine($"  (Skills listing not available: {ex.Message})");
-}
-
-Console.WriteLine();
-
-// Define the pptx skill - the SDK handles all beta flags and container configuration automatically
-// when using AsAITool(), so no manual RawRepresentationFactory configuration is needed.
-BetaSkillParams pptxSkill = new()
-{
-    Type = BetaSkillParamsType.Anthropic,
-    SkillID = "pptx",
-    Version = "latest"
-};
-
-// Create an agent with the pptx skill enabled.
-// Skills require extended thinking and higher max tokens for complex file generation.
-// The SDK's AsAITool() handles beta flags and container config automatically.
-ChatClientAgent agent = anthropicClient.Beta.AsAIAgent(
-    model: model,
-    instructions: "You are a helpful agent for creating PowerPoint presentations.",
-    tools: [pptxSkill.AsAITool()],
-    clientFactory: (chatClient) => chatClient
-        .AsBuilder()
-        .ConfigureOptions(options =>
-        {
-            options.RawRepresentationFactory = (_) => new MessageCreateParams()
-            {
-                Model = model,
-                MaxTokens = 20000,
-                Messages = [],
-                Thinking = new BetaThinkingConfigParam(
-                    new BetaThinkingConfigEnabled(budgetTokens: 10000))
-            };
-        })
-        .Build());
-
-Console.WriteLine("Creating a presentation about renewable energy...\n");
-
-// Run the agent with a request to create a presentation
-AgentResponse response = await agent.RunAsync("Create a simple 3-slide presentation about renewable energy sources. Include a title slide, a slide about solar energy, and a slide about wind energy.");
-
-Console.WriteLine("#### Agent Response ####");
-Console.WriteLine(response.Text);
-
-// Display any reasoning/thinking content
-List<TextReasoningContent> reasoningContents = response.Messages.SelectMany(m => m.Contents.OfType<TextReasoningContent>()).ToList();
-if (reasoningContents.Count > 0)
-{
-    Console.WriteLine("\n#### Agent Reasoning ####");
-    Console.WriteLine($"\e[92m{string.Join("\n", reasoningContents.Select(c => c.Text))}\e[0m");
-}
-
-// Collect generated files from CodeInterpreterToolResultContent outputs
-List<HostedFileContent> hostedFiles = response.Messages
-    .SelectMany(m => m.Contents.OfType<CodeInterpreterToolResultContent>())
-    .Where(c => c.Outputs is not null)
-    .SelectMany(c => c.Outputs!.OfType<HostedFileContent>())
-    .ToList();
-
-if (hostedFiles.Count > 0)
-{
-    Console.WriteLine("\n#### Generated Files ####");
-    foreach (HostedFileContent file in hostedFiles)
-    {
-        Console.WriteLine($"  FileId: {file.FileId}");
-
-        // Download the file using the Anthropic Files API
-        using HttpResponse fileResponse = await anthropicClient.Beta.Files.Download(
-            file.FileId,
-            new FileDownloadParams { Betas = ["files-api-2025-04-14"] });
-
-        // Save the file to disk
-        string fileName = $"presentation_{file.FileId.Substring(0, 8)}.pptx";
-        using FileStream fileStream = File.Create(fileName);
-        Stream contentStream = await fileResponse.ReadAsStream();
-        await contentStream.CopyToAsync(fileStream);
-
-        Console.WriteLine($"  Saved to: {fileName}");
-    }
-}
-
-Console.WriteLine("\nToken usage:");
-Console.WriteLine($"Input: {response.Usage?.InputTokenCount}, Output: {response.Usage?.OutputTokenCount}");
-if (response.Usage?.AdditionalCounts is not null)
-{
-    Console.WriteLine($"Additional: {string.Join(", ", response.Usage.AdditionalCounts)}");
-}

dotnet/samples/02-agents/AgentWithAnthropic/Agent_Anthropic_Step04_UsingSkills/README.md

@@ -1,119 +0,0 @@
-# Using Anthropic Skills with agents
-
-This sample demonstrates how to use Anthropic-managed Skills with AI agents. Skills are pre-built capabilities provided by Anthropic that can be used with the Claude API.
-
-## What this sample demonstrates
-
-- Listing available Anthropic-managed skills
-- Creating an AI agent with Anthropic Claude Skills support using the simplified `AsAITool()` approach
-- Using the pptx skill to create PowerPoint presentations
-- Downloading and saving generated files to disk
-- Handling agent responses with generated content
-
-## Prerequisites
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 10.0 SDK or later
-- Anthropic API key configured
-- Access to Anthropic Claude models with Skills support
-
-**Note**: This sample uses Anthropic Claude models with Skills. Skills are a beta feature. For more information, see [Anthropic documentation](https://docs.anthropic.com/).
-
-Set the following environment variables:
-
-```powershell
-$env:ANTHROPIC_API_KEY="your-anthropic-api-key"  # Replace with your Anthropic API key
-$env:ANTHROPIC_CHAT_MODEL_NAME="your-anthropic-model"  # Replace with your Anthropic model (e.g., claude-sonnet-4-5-20250929)
-```
-
-## Run the sample
-
-Navigate to the AgentWithAnthropic sample directory and run:
-
-```powershell
-cd dotnet\samples\02-agents\AgentWithAnthropic
-dotnet run --project .\Agent_Anthropic_Step04_UsingSkills
-```
-
-## Available Anthropic Skills
-
-Anthropic provides several managed skills that can be used with the Claude API:
-
-- `pptx` - Create PowerPoint presentations
-- `xlsx` - Create Excel spreadsheets
-- `docx` - Create Word documents
-- `pdf` - Create and analyze PDF documents
-
-You can list available skills using the Anthropic SDK:
-
-```csharp
-SkillListPage skills = await anthropicClient.Beta.Skills.List(
-    new SkillListParams { Source = "anthropic", Betas = [AnthropicBeta.Skills2025_10_02] });
-
-foreach (var skill in skills.Items)
-{
-    Console.WriteLine($"{skill.Source}: {skill.ID} (version: {skill.LatestVersion})");
-}
-```
-
-## Expected behavior
-
-The sample will:
-
-1. List all available Anthropic-managed skills
-2. Create an agent with the pptx skill enabled
-3. Run the agent with a request to create a presentation
-4. Display the agent's response text
-5. Download any generated files and save them to disk
-6. Display token usage statistics
-
-## Code highlights
-
-### Simplified skill configuration
-
-The Anthropic SDK handles all beta flags and container configuration automatically when using `AsAITool()`:
-
-```csharp
-// Define the pptx skill
-BetaSkillParams pptxSkill = new()
-{
-    Type = BetaSkillParamsType.Anthropic,
-    SkillID = "pptx",
-    Version = "latest"
-};
-
-// Create an agent - the SDK handles beta flags automatically!
-ChatClientAgent agent = anthropicClient.Beta.AsAIAgent(
-    model: model,
-    instructions: "You are a helpful agent for creating PowerPoint presentations.",
-    tools: [pptxSkill.AsAITool()]);
-```
-
-**Note**: No manual `RawRepresentationFactory`, `Betas`, or `Container` configuration is needed. The SDK automatically adds the required beta headers (`skills-2025-10-02`, `code-execution-2025-08-25`) and configures the container with the skill.
-
-### Handling generated files
-
-Generated files are returned as `HostedFileContent` within `CodeInterpreterToolResultContent`:
-
-```csharp
-// Collect generated files from response
-List<HostedFileContent> hostedFiles = response.Messages
-    .SelectMany(m => m.Contents.OfType<CodeInterpreterToolResultContent>())
-    .Where(c => c.Outputs is not null)
-    .SelectMany(c => c.Outputs!.OfType<HostedFileContent>())
-    .ToList();
-
-// Download and save each file
-foreach (HostedFileContent file in hostedFiles)
-{
-    using HttpResponse fileResponse = await anthropicClient.Beta.Files.Download(
-        file.FileId,
-        new FileDownloadParams { Betas = ["files-api-2025-04-14"] });
-
-    string fileName = $"presentation_{file.FileId.Substring(0, 8)}.pptx";
-    await using FileStream fileStream = File.Create(fileName);
-    Stream contentStream = await fileResponse.ReadAsStream();
-    await contentStream.CopyToAsync(fileStream);
-}
-```

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/Program.cs

@@ -1,68 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to use the Mem0Provider to persist and recall memories for an agent.
-// The sample stores conversation messages in a Mem0 service and retrieves relevant memories
-// for subsequent invocations, even across new sessions.
-
-using System.Net.Http.Headers;
-using System.Text.Json;
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.Mem0;
-using Microsoft.Extensions.AI;
-using OpenAI.Chat;
-
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-var mem0ServiceUri = Environment.GetEnvironmentVariable("MEM0_ENDPOINT") ?? throw new InvalidOperationException("MEM0_ENDPOINT is not set.");
-var mem0ApiKey = Environment.GetEnvironmentVariable("MEM0_API_KEY") ?? throw new InvalidOperationException("MEM0_API_KEY is not set.");
-
-// Create an HttpClient for Mem0 with the required base address and authentication.
-using HttpClient mem0HttpClient = new();
-mem0HttpClient.BaseAddress = new Uri(mem0ServiceUri);
-mem0HttpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Token", mem0ApiKey);
-
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent(new ChatClientAgentOptions()
-    {
-        ChatOptions = new() { Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details." },
-        // The stateInitializer can be used to customize the Mem0 scope per session and it will be called each time a session
-        // is encountered by the Mem0Provider that does not already have Mem0Provider state stored on the session.
-        // If each session should have its own Mem0 scope, you can create a new id per session via the stateInitializer, e.g.:
-        // new Mem0Provider(mem0HttpClient, stateInitializer: _ => new(new Mem0ProviderScope() { ThreadId = Guid.NewGuid().ToString() }))
-        // In our case we are storing memories scoped by application and user instead so that memories are retained across threads.
-        AIContextProviders = [new Mem0Provider(mem0HttpClient, stateInitializer: _ => new(new Mem0ProviderScope() { ApplicationId = "getting-started-agents", UserId = "sample-user" }))]
-    });
-
-AgentSession session = await agent.CreateSessionAsync();
-
-// Clear any existing memories for this scope to demonstrate fresh behavior.
-// Note that the ClearStoredMemoriesAsync method will clear memories
-// using the scope stored in the session, or provided via the stateInitializer.
-Mem0Provider mem0Provider = agent.GetService<Mem0Provider>()!;
-await mem0Provider.ClearStoredMemoriesAsync(session);
-
-Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", session));
-Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", session));
-
-Console.WriteLine("\nWaiting briefly for Mem0 to index the new memories...\n");
-await Task.Delay(TimeSpan.FromSeconds(2));
-
-Console.WriteLine(await agent.RunAsync("What do you already know about my upcoming trip?", session));
-
-Console.WriteLine("\n>> Serialize and deserialize the session to demonstrate persisted state\n");
-JsonElement serializedSession = await agent.SerializeSessionAsync(session);
-AgentSession restoredSession = await agent.DeserializeSessionAsync(serializedSession);
-Console.WriteLine(await agent.RunAsync("Can you recap the personal details you remember?", restoredSession));
-
-Console.WriteLine("\n>> Start a new session that shares the same Mem0 scope\n");
-AgentSession newSession = await agent.CreateSessionAsync();
-Console.WriteLine(await agent.RunAsync("Summarize what you already know about me.", newSession));

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/AgentWithMemory_Step04_MemoryUsingFoundry.csproj

@@ -1,21 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Azure.AI.Projects" />
-    <PackageReference Include="Azure.Identity" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.FoundryMemory\Microsoft.Agents.AI.FoundryMemory.csproj" />
-  </ItemGroup>
-
-</Project>

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/Program.cs

@@ -1,77 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to use the FoundryMemoryProvider to persist and recall memories for an agent.
-// The sample stores conversation messages in an Azure AI Foundry memory store and retrieves relevant
-// memories for subsequent invocations, even across new sessions.
-//
-// Note: Memory extraction in Azure AI Foundry is asynchronous and takes time. This sample demonstrates
-// a simple polling approach to wait for memory updates to complete before querying.
-
-using System.Text.Json;
-using Azure.AI.Projects;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.FoundryMemory;
-
-string foundryEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-string memoryStoreName = Environment.GetEnvironmentVariable("AZURE_AI_MEMORY_STORE_ID") ?? "memory-store-sample";
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-string embeddingModelName = Environment.GetEnvironmentVariable("AZURE_AI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-ada-002";
-
-// Create an AIProjectClient for Foundry with Azure Identity authentication.
-DefaultAzureCredential credential = new();
-AIProjectClient projectClient = new(new Uri(foundryEndpoint), credential);
-
-// Get the ChatClient from the AIProjectClient's OpenAI property using the deployment name.
-// The stateInitializer can be used to customize the Foundry Memory scope per session and it will be called each time a session
-// is encountered by the FoundryMemoryProvider that does not already have state stored on the session.
-// If each session should have its own scope, you can create a new id per session via the stateInitializer, e.g.:
-// new FoundryMemoryProvider(projectClient, memoryStoreName, stateInitializer: _ => new(new FoundryMemoryProviderScope(Guid.NewGuid().ToString())), ...)
-// In our case we are storing memories scoped by user so that memories are retained across sessions.
-FoundryMemoryProvider memoryProvider = new(
-    projectClient,
-    memoryStoreName,
-    stateInitializer: _ => new(new FoundryMemoryProviderScope("sample-user-123")));
-
-AIAgent agent = await projectClient.CreateAIAgentAsync(deploymentName,
-    options: new ChatClientAgentOptions()
-    {
-        Name = "TravelAssistantWithFoundryMemory",
-        ChatOptions = new() { Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details." },
-        AIContextProviders = [memoryProvider]
-    });
-
-AgentSession session = await agent.CreateSessionAsync();
-
-Console.WriteLine("\n>> Setting up Foundry Memory Store\n");
-
-// Ensure the memory store exists (creates it with the specified models if needed).
-await memoryProvider.EnsureMemoryStoreCreatedAsync(deploymentName, embeddingModelName, "Sample memory store for travel assistant");
-
-// Clear any existing memories for this scope to demonstrate fresh behavior.
-await memoryProvider.EnsureStoredMemoriesDeletedAsync(session);
-
-Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", session));
-Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", session));
-
-// Memory extraction in Azure AI Foundry is asynchronous and takes time to process.
-// WhenUpdatesCompletedAsync polls all pending updates and waits for them to complete.
-Console.WriteLine("\nWaiting for Foundry Memory to process updates...");
-await memoryProvider.WhenUpdatesCompletedAsync();
-
-Console.WriteLine("Updates completed.\n");
-
-Console.WriteLine(await agent.RunAsync("What do you already know about my upcoming trip?", session));
-
-Console.WriteLine("\n>> Serialize and deserialize the session to demonstrate persisted state\n");
-JsonElement serializedSession = await agent.SerializeSessionAsync(session);
-AgentSession restoredSession = await agent.DeserializeSessionAsync(serializedSession);
-Console.WriteLine(await agent.RunAsync("Can you recap the personal details you remember?", restoredSession));
-
-Console.WriteLine("\n>> Start a new session that shares the same Foundry Memory scope\n");
-
-Console.WriteLine("\nWaiting for Foundry Memory to process updates...");
-await memoryProvider.WhenUpdatesCompletedAsync();
-
-AgentSession newSession = await agent.CreateSessionAsync();
-Console.WriteLine(await agent.RunAsync("Summarize what you already know about me.", newSession));

dotnet/samples/02-agents/AgentWithMemory/AgentWithMemory_Step04_MemoryUsingFoundry/README.md

@@ -1,57 +0,0 @@
-# Agent with Memory Using Azure AI Foundry
-
-This sample demonstrates how to create and run an agent that uses Azure AI Foundry's managed memory service to extract and retrieve individual memories across sessions.
-
-## Features Demonstrated
-
-- Creating a `FoundryMemoryProvider` with Azure Identity authentication
-- Automatic memory store creation if it doesn't exist
-- Multi-turn conversations with automatic memory extraction
-- Memory retrieval to inform agent responses
-- Session serialization and deserialization
-- Memory persistence across completely new sessions
-
-## Prerequisites
-
-1. Azure subscription with Azure AI Foundry project
-2. Azure OpenAI resource with a chat model deployment (e.g., gpt-4o-mini) and an embedding model deployment (e.g., text-embedding-ada-002)
-3. .NET 10.0 SDK
-4. Azure CLI logged in (`az login`)
-
-## Environment Variables
-
-```bash
-# Azure AI Foundry project endpoint and memory store name
-export AZURE_AI_PROJECT_ENDPOINT="https://your-account.services.ai.azure.com/api/projects/your-project"
-export AZURE_AI_MEMORY_STORE_ID="my_memory_store"
-
-# Model deployment names (models deployed in your Foundry project)
-export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
-export AZURE_AI_EMBEDDING_DEPLOYMENT_NAME="text-embedding-ada-002"
-```
-
-## Run the Sample
-
-```bash
-dotnet run
-```
-
-## Expected Output
-
-The agent will:
-1. Create the memory store if it doesn't exist (using the specified chat and embedding models)
-2. Learn your name (Taylor), travel destination (Patagonia), timing (November), companions (sister), and interests (scenic viewpoints)
-3. Wait for Foundry Memory to index the memories
-4. Recall those details when asked about the trip
-5. Demonstrate memory persistence across session serialization/deserialization
-6. Show that a brand new session can still access the same memories
-
-## Key Differences from Mem0
-
-| Aspect | Mem0 | Azure AI Foundry Memory |
-|--------|------|------------------------|
-| Authentication | API Key | Azure Identity (DefaultAzureCredential) |
-| Scope | ApplicationId, UserId, AgentId, ThreadId | Single `Scope` string |
-| Memory Types | Single memory store | User Profile + Chat Summary |
-| Hosting | Mem0 cloud or self-hosted | Azure AI Foundry managed service |
-| Store Creation | N/A (automatic) | Explicit via `EnsureMemoryStoreCreatedAsync` |

dotnet/samples/02-agents/Agents/Agent_Step02_StructuredOutput/AIAgentBuilderExtensions.cs

@@ -1,49 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using Microsoft.Extensions.DependencyInjection;
-
-namespace SampleApp;
-
-/// <summary>
-/// Provides extension methods for adding structured output capabilities to <see cref="AIAgentBuilder"/> instances.
-/// </summary>
-internal static class AIAgentBuilderExtensions
-{
-    /// <summary>
-    /// Adds structured output capabilities to the agent pipeline, enabling conversion of text responses to structured JSON format.
-    /// </summary>
-    /// <param name="builder">The <see cref="AIAgentBuilder"/> to which structured output support will be added.</param>
-    /// <param name="chatClient">
-    /// The chat client used to transform text responses into structured JSON format.
-    /// If <see langword="null"/>, the chat client will be resolved from the service provider.
-    /// </param>
-    /// <param name="optionsFactory">
-    /// An optional factory function that returns the <see cref="StructuredOutputAgentOptions"/> instance to use.
-    /// This allows for fine-tuning the structured output behavior such as setting the response format or system message.
-    /// </param>
-    /// <returns>The <see cref="AIAgentBuilder"/> with structured output capabilities added, enabling method chaining.</returns>
-    /// <remarks>
-    /// <para>
-    /// A <see cref="ChatResponseFormatJson"/> must be specified either through the
-    /// <see cref="AgentRunOptions.ResponseFormat"/> at runtime or the <see cref="StructuredOutputAgentOptions.ChatOptions"/>
-    /// provided during configuration.
-    /// </para>
-    /// </remarks>
-    public static AIAgentBuilder UseStructuredOutput(
-        this AIAgentBuilder builder,
-        IChatClient? chatClient = null,
-        Func<StructuredOutputAgentOptions>? optionsFactory = null)
-    {
-        ArgumentNullException.ThrowIfNull(builder);
-
-        return builder.Use((innerAgent, services) =>
-        {
-            chatClient ??= services?.GetService<IChatClient>()
-                ?? throw new InvalidOperationException($"No {nameof(IChatClient)} was provided and none could be resolved from the service provider. Either provide an {nameof(IChatClient)} explicitly or register one in the dependency injection container.");
-
-            return new StructuredOutputAgent(innerAgent, chatClient, optionsFactory?.Invoke());
-        });
-    }
-}

dotnet/samples/02-agents/Agents/Agent_Step02_StructuredOutput/Program.cs

@@ -1,183 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to configure ChatClientAgent to produce structured output.
-
-using System.ComponentModel;
-using System.Text.Json;
-using System.Text.Json.Serialization;
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using OpenAI.Chat;
-using SampleApp;
-using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
-
-string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-// Create chat client to be used by chat client agents.
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-ChatClient chatClient = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-        .GetChatClient(deploymentName);
-
-// Demonstrates how to work with structured output via ResponseFormat with the non-generic RunAsync method.
-// This approach is useful when:
-// a. Structured output is used for inter-agent communication, where one agent produces structured output
-//    and passes it as text to another agent as input, without the need for the caller to directly work with the structured output.
-// b. The type of the structured output is not known at compile time, so the generic RunAsync<T> method cannot be used.
-// c. The type of the structured output is represented by JSON schema only, without a corresponding class or type in the code.
-await UseStructuredOutputWithResponseFormatAsync(chatClient);
-
-// Demonstrates how to work with structured output via the generic RunAsync<T> method.
-// This approach is useful when the caller needs to directly work with the structured output in the code
-// via an instance of the corresponding class or type and the type is known at compile time.
-await UseStructuredOutputWithRunAsync(chatClient);
-
-// Demonstrates how to work with structured output when streaming using the RunStreamingAsync method.
-await UseStructuredOutputWithRunStreamingAsync(chatClient);
-
-// Demonstrates how to add structured output support to agents that don't natively support it using the structured output middleware.
-// This approach is useful when working with agents that don't support structured output natively, or agents using models
-// that don't have the capability to produce structured output, allowing you to still leverage structured output features by transforming
-// the text output from the agent into structured data using a chat client.
-await UseStructuredOutputWithMiddlewareAsync(chatClient);
-
-static async Task UseStructuredOutputWithResponseFormatAsync(ChatClient chatClient)
-{
-    Console.WriteLine("=== Structured Output with ResponseFormat ===");
-
-    // Create the agent
-    AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
-    {
-        Name = "HelpfulAssistant",
-        ChatOptions = new()
-        {
-            Instructions = "You are a helpful assistant.",
-            // Specify CityInfo as the type parameter of ForJsonSchema to indicate the expected structured output from the agent.
-            ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<CityInfo>()
-        }
-    });
-
-    // Invoke the agent with some unstructured input to extract the structured information from.
-    AgentResponse response = await agent.RunAsync("Provide information about the capital of France.");
-
-    // Access the structured output via the Text property of the agent response as JSON in scenarios when JSON as text is required
-    // and no object instance is needed (e.g., for logging, forwarding to another service, or storing in a database).
-    Console.WriteLine("Assistant Output (JSON):");
-    Console.WriteLine(response.Text);
-    Console.WriteLine();
-
-    // Deserialize the JSON text to work with the structured object in scenarios when you need to access properties,
-    // perform operations, or pass the data to methods that require the typed object instance.
-    CityInfo cityInfo = JsonSerializer.Deserialize<CityInfo>(response.Text)!;
-
-    Console.WriteLine("Assistant Output (Deserialized):");
-    Console.WriteLine($"Name: {cityInfo.Name}");
-    Console.WriteLine();
-}
-
-static async Task UseStructuredOutputWithRunAsync(ChatClient chatClient)
-{
-    Console.WriteLine("=== Structured Output with RunAsync<T> ===");
-
-    // Create the agent
-    AIAgent agent = chatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
-
-    // Set CityInfo as the type parameter of RunAsync method to specify the expected structured output from the agent and invoke it with some unstructured input.
-    AgentResponse<CityInfo> response = await agent.RunAsync<CityInfo>("Provide information about the capital of France.");
-
-    // Access the structured output via the Result property of the agent response.
-    CityInfo cityInfo = response.Result;
-
-    Console.WriteLine("Assistant Output:");
-    Console.WriteLine($"Name: {cityInfo.Name}");
-    Console.WriteLine();
-}
-
-static async Task UseStructuredOutputWithRunStreamingAsync(ChatClient chatClient)
-{
-    Console.WriteLine("=== Structured Output with RunStreamingAsync ===");
-
-    // Create the agent
-    AIAgent agent = chatClient.AsAIAgent(new ChatClientAgentOptions()
-    {
-        Name = "HelpfulAssistant",
-        ChatOptions = new()
-        {
-            Instructions = "You are a helpful assistant.",
-            // Specify CityInfo as the type parameter of ForJsonSchema to indicate the expected structured output from the agent.
-            ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<CityInfo>()
-        }
-    });
-
-    // Invoke the agent with some unstructured input while streaming, to extract the structured information from.
-    IAsyncEnumerable<AgentResponseUpdate> updates = agent.RunStreamingAsync("Provide information about the capital of France.");
-
-    // Assemble all the parts of the streamed output.
-    AgentResponse nonGenericResponse = await updates.ToAgentResponseAsync();
-
-    // Access the structured output by deserializing JSON in the Text property.
-    CityInfo cityInfo = JsonSerializer.Deserialize<CityInfo>(nonGenericResponse.Text)!;
-
-    Console.WriteLine("Assistant Output:");
-    Console.WriteLine($"Name: {cityInfo.Name}");
-    Console.WriteLine();
-}
-
-static async Task UseStructuredOutputWithMiddlewareAsync(ChatClient chatClient)
-{
-    Console.WriteLine("=== Structured Output with UseStructuredOutput Middleware ===");
-
-    // Create chat client that will transform the agent text response into structured output.
-    IChatClient meaiChatClient = chatClient.AsIChatClient();
-
-    // Create the agent
-    AIAgent agent = meaiChatClient.AsAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
-
-    // Add structured output middleware via UseStructuredOutput method to add structured output support to the agent.
-    // This middleware transforms the agent's text response into structured data using a chat client.
-    // Since our agent does support structured output natively, we will add a middleware that removes ResponseFormat
-    //  from the AgentRunOptions to emulate an agent that doesn't support structured output natively
-    agent = agent
-        .AsBuilder()
-        .UseStructuredOutput(meaiChatClient)
-        .Use(ResponseFormatRemovalMiddleware, null)
-        .Build();
-
-    // Set CityInfo as the type parameter of RunAsync method to specify the expected structured output from the agent and invoke it with some unstructured input.
-    AgentResponse<CityInfo> response = await agent.RunAsync<CityInfo>("Provide information about the capital of France.");
-
-    // Access the structured output via the Result property of the agent response.
-    CityInfo cityInfo = response.Result;
-
-    Console.WriteLine("Assistant Output:");
-    Console.WriteLine($"Name: {cityInfo.Name}");
-    Console.WriteLine();
-}
-
-static Task<AgentResponse> ResponseFormatRemovalMiddleware(IEnumerable<ChatMessage> messages, AgentSession? session, AgentRunOptions? options, AIAgent innerAgent, CancellationToken cancellationToken)
-{
-    // Remove any ResponseFormat from the options to emulate an agent that doesn't support structured output natively.
-    options = options?.Clone();
-    options?.ResponseFormat = null;
-
-    return innerAgent.RunAsync(messages, session, options, cancellationToken);
-}
-
-namespace SampleApp
-{
-    /// <summary>
-    /// Represents information about a city, including its name.
-    /// </summary>
-    [Description("Information about a city")]
-    public sealed class CityInfo
-    {
-        [JsonPropertyName("name")]
-        public string? Name { get; set; }
-    }
-}

dotnet/samples/02-agents/Agents/Agent_Step02_StructuredOutput/README.md

@@ -1,52 +0,0 @@
-# Structured Output with ChatClientAgent
-
-This sample demonstrates how to configure ChatClientAgent to produce structured output in JSON format using various approaches.
-
-## What this sample demonstrates
-
-- **ResponseFormat approach**: Configuring agents with JSON schema response format via `ChatResponseFormat.ForJsonSchema<T>()` for inter-agent communication or when the type is not known at compile time
-- **Generic RunAsync<T> method**: Using the generic `RunAsync<T>` method for structured output when the caller needs to work directly with typed objects
-- **Structured output with Streaming**: Using `RunStreamingAsync` to stream responses while still obtaining structured output by assembling and deserializing the streamed content
-- **StructuredOutput middleware**: Adding structured output support to agents that don't natively support it (like A2A agents or models without structured output capability) by transforming text output into structured data using a chat client
-
-## Prerequisites
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 10 SDK or later
-- Azure OpenAI service endpoint and deployment configured
-- Azure CLI installed and authenticated (for Azure credential authentication)
-- User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource
-
-**Note**: This sample uses Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).
-
-**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource and have the `Cognitive Services OpenAI Contributor` role. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
-
-## Environment Variables
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" # Replace with your Azure OpenAI resource endpoint
-$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
-```
-
-## Run the sample
-
-Navigate to the sample directory and run:
-
-```powershell
-cd dotnet/samples/02-agents/Agents/Agent_Step02_StructuredOutput
-dotnet run
-```
-
-## Expected behavior
-
-The sample will demonstrate four different approaches to structured output:
-
-1. **Structured Output with ResponseFormat**: Creates an agent with `ResponseFormat` set to `ForJsonSchema<CityInfo>()`, invokes it with unstructured input, and accesses the structured output via the `Text` property
-2. **Structured Output with RunAsync<T>**: Creates an agent and uses the generic `RunAsync<CityInfo>()` method to get a typed `AgentResponse<CityInfo>` with the result accessible via the `Result` property
-3. **Structured Output with RunStreamingAsync**: Creates an agent with JSON schema response format, streams the response using `RunStreamingAsync`, assembles the updates using `ToAgentResponseAsync()`, and deserializes the JSON text into a typed object
-4. **Structured Output with StructuredOutput Middleware**: Uses the `UseStructuredOutput` method on `AIAgentBuilder` to add structured output support to agents that don't natively support it
-
-Each approach will output information about the capital of France (Paris) in a structured format.

dotnet/samples/02-agents/Agents/Agent_Step02_StructuredOutput/StructuredOutputAgent.cs

@@ -1,88 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-namespace SampleApp;
-
-/// <summary>
-/// A delegating AI agent that converts text responses from an inner AI agent into structured output using a chat client.
-/// </summary>
-/// <remarks>
-/// <para>
-/// The <see cref="StructuredOutputAgent"/> wraps an inner agent and uses a chat client to transform
-/// the inner agent's text response into a structured JSON format based on the specified response format.
-/// </para>
-/// <para>
-/// This agent requires a <see cref="ChatResponseFormatJson"/> to be specified either through the
-/// <see cref="AgentRunOptions.ResponseFormat"/> or the <see cref="StructuredOutputAgentOptions.ChatOptions"/>
-/// provided during construction.
-/// </para>
-/// </remarks>
-internal sealed class StructuredOutputAgent : DelegatingAIAgent
-{
-    private readonly IChatClient _chatClient;
-    private readonly StructuredOutputAgentOptions? _agentOptions;
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="StructuredOutputAgent"/> class.
-    /// </summary>
-    /// <param name="innerAgent">The underlying agent that generates text responses to be converted to structured output.</param>
-    /// <param name="chatClient">The chat client used to transform text responses into structured JSON format.</param>
-    /// <param name="options">Optional configuration options for the structured output agent.</param>
-    public StructuredOutputAgent(AIAgent innerAgent, IChatClient chatClient, StructuredOutputAgentOptions? options = null)
-        : base(innerAgent)
-    {
-        this._chatClient = chatClient ?? throw new ArgumentNullException(nameof(chatClient));
-        this._agentOptions = options;
-    }
-
-    /// <inheritdoc />
-    protected override async Task<AgentResponse> RunCoreAsync(
-        IEnumerable<ChatMessage> messages,
-        AgentSession? session = null,
-        AgentRunOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-        // Run the inner agent first, to get back the text response we want to convert.
-        var textResponse = await this.InnerAgent.RunAsync(messages, session, options, cancellationToken).ConfigureAwait(false);
-
-        // Invoke the chat client to transform the text output into structured data.
-        ChatResponse soResponse = await this._chatClient.GetResponseAsync(
-            messages: this.GetChatMessages(textResponse.Text),
-            options: this.GetChatOptions(options),
-            cancellationToken: cancellationToken).ConfigureAwait(false);
-
-        return new StructuredOutputAgentResponse(soResponse, textResponse);
-    }
-
-    private List<ChatMessage> GetChatMessages(string? textResponseText)
-    {
-        List<ChatMessage> chatMessages = [];
-
-        if (this._agentOptions?.ChatClientSystemMessage is not null)
-        {
-            chatMessages.Add(new ChatMessage(ChatRole.System, this._agentOptions.ChatClientSystemMessage));
-        }
-
-        chatMessages.Add(new ChatMessage(ChatRole.User, textResponseText));
-
-        return chatMessages;
-    }
-
-    private ChatOptions GetChatOptions(AgentRunOptions? options)
-    {
-        ChatResponseFormat responseFormat = options?.ResponseFormat
-            ?? this._agentOptions?.ChatOptions?.ResponseFormat
-            ?? throw new InvalidOperationException($"A response format of type '{nameof(ChatResponseFormatJson)}' must be specified, but none was specified.");
-
-        if (responseFormat is not ChatResponseFormatJson jsonResponseFormat)
-        {
-            throw new NotSupportedException($"A response format of type '{nameof(ChatResponseFormatJson)}' must be specified, but was '{responseFormat.GetType().Name}'.");
-        }
-
-        var chatOptions = this._agentOptions?.ChatOptions?.Clone() ?? new ChatOptions();
-        chatOptions.ResponseFormat = jsonResponseFormat;
-        return chatOptions;
-    }
-}

dotnet/samples/02-agents/Agents/Agent_Step02_StructuredOutput/StructuredOutputAgentOptions.cs

@@ -1,31 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-namespace SampleApp;
-
-/// <summary>
-/// Represents configuration options for a <see cref="StructuredOutputAgent"/>.
-/// </summary>
-#pragma warning disable CA1812 // Instantiated via AIAgentBuilderExtensions.UseStructuredOutput optionsFactory parameter
-internal sealed class StructuredOutputAgentOptions
-#pragma warning restore CA1812
-{
-    /// <summary>
-    /// Gets or sets the system message to use when invoking the chat client for structured output conversion.
-    /// </summary>
-    public string? ChatClientSystemMessage { get; set; }
-
-    /// <summary>
-    /// Gets or sets the chat options to use for the structured output conversion by the chat client
-    /// used by the agent.
-    /// </summary>
-    /// <remarks>
-    /// This property is optional. The <see cref="ChatOptions.ResponseFormat"/> should be set to a
-    /// <see cref="ChatResponseFormatJson"/> instance to specify the expected JSON schema for the structured output.
-    /// Note that if <see cref="AgentRunOptions.ResponseFormat"/> is provided when running the agent,
-    /// it will take precedence and override the <see cref="ChatOptions.ResponseFormat"/> specified here.
-    /// </remarks>
-    public ChatOptions? ChatOptions { get; set; }
-}

dotnet/samples/02-agents/Agents/Agent_Step02_StructuredOutput/StructuredOutputAgentResponse.cs

@@ -1,28 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-namespace SampleApp;
-
-/// <summary>
-/// Represents an agent response that contains structured output and
-/// the original agent response from which the structured output was generated.
-/// </summary>
-internal sealed class StructuredOutputAgentResponse : AgentResponse
-{
-    /// <summary>
-    /// Initializes a new instance of the <see cref="StructuredOutputAgentResponse"/> class.
-    /// </summary>
-    /// <param name="chatResponse">The <see cref="ChatResponse"/> containing the structured output.</param>
-    /// <param name="agentResponse">The original <see cref="AgentResponse"/> from the inner agent.</param>
-    public StructuredOutputAgentResponse(ChatResponse chatResponse, AgentResponse agentResponse) : base(chatResponse)
-    {
-        this.OriginalResponse = agentResponse;
-    }
-
-    /// <summary>
-    /// Gets the original non-structured response from the inner agent used by chat client to produce the structured output.
-    /// </summary>
-    public AgentResponse OriginalResponse { get; }
-}

dotnet/samples/02-agents/Agents/Agent_Step03_PersistedConversations/Program.cs

@@ -1,45 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-#pragma warning disable CA1869 // Cache and reuse 'JsonSerializerOptions' instances
-
-// This sample shows how to create and use a simple AI agent with a conversation that can be persisted to disk.
-
-using System.Text.Json;
-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";
-
-// Create the agent
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");
-
-// Start a new session for the agent conversation.
-AgentSession session = await agent.CreateSessionAsync();
-
-// Run the agent with a new session.
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
-
-// Serialize the session state to a JsonElement, so it can be stored for later use.
-JsonElement serializedSession = await agent.SerializeSessionAsync(session);
-
-// In a real application, you would typically write the serialized session to a file or
-// database for persistence, and read it back when resuming the conversation.
-// Here we'll just write the serialized session to console (for demonstration purposes).
-Console.WriteLine("\n--- Serialized session ---\n");
-Console.WriteLine(JsonSerializer.Serialize(serializedSession, new JsonSerializerOptions { WriteIndented = true }) + "\n");
-
-// Deserialize the session state after loading from storage.
-AgentSession resumedSession = await agent.DeserializeSessionAsync(serializedSession);
-
-// Run the agent again with the resumed session.
-Console.WriteLine(await agent.RunAsync("Now tell the same joke in the voice of a pirate, and add some emojis to the joke.", resumedSession));

dotnet/samples/02-agents/Agents/Agent_Step04_3rdPartyChatHistoryStorage/Program.cs

@@ -1,172 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-#pragma warning disable CA1869 // Cache and reuse 'JsonSerializerOptions' instances
-
-// This sample shows how to create and use a simple AI agent with custom ChatHistoryProvider that stores chat history in a custom storage location.
-// The state of the custom ChatHistoryProvider (SessionDbKey) is stored in the AgentSession's StateBag, so that when the session is resumed later,
-// the chat history can be retrieved from the custom storage location.
-
-using System.Text.Json;
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using Microsoft.Extensions.VectorData;
-using Microsoft.SemanticKernel.Connectors.InMemory;
-using OpenAI.Chat;
-using SampleApp;
-using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
-
-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";
-
-// Create a vector store to store the chat messages in.
-// Replace this with a vector store implementation of your choice if you want to persist the chat history to disk.
-VectorStore vectorStore = new InMemoryVectorStore();
-
-// Create the agent
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent(new ChatClientAgentOptions
-    {
-        ChatOptions = new() { Instructions = "You are good at telling jokes." },
-        Name = "Joker",
-        // Create a new ChatHistoryProvider for this agent that stores chat history in a vector store.
-        ChatHistoryProvider = new VectorChatHistoryProvider(vectorStore)
-    });
-
-// Start a new session for the agent conversation.
-AgentSession session = await agent.CreateSessionAsync();
-
-// Run the agent with the session that stores chat history in the vector store.
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
-
-// Serialize the session state, so it can be stored for later use.
-// Since the chat history is stored in the vector store, the serialized session
-// only contains the guid that the messages are stored under in the vector store.
-JsonElement serializedSession = await agent.SerializeSessionAsync(session);
-
-Console.WriteLine("\n--- Serialized session ---\n");
-Console.WriteLine(JsonSerializer.Serialize(serializedSession, new JsonSerializerOptions { WriteIndented = true }));
-
-// The serialized session can now be saved to a database, file, or any other storage mechanism
-// and loaded again later.
-
-// Deserialize the session state after loading from storage.
-AgentSession resumedSession = await agent.DeserializeSessionAsync(serializedSession);
-
-// Run the agent with the session that stores chat history in the vector store a second time.
-Console.WriteLine(await agent.RunAsync("Now tell the same joke in the voice of a pirate, and add some emojis to the joke.", resumedSession));
-
-// We can access the VectorChatHistoryProvider via the agent's GetService method
-// if we need to read the key under which chat history is stored. The key is stored
-// in the session state, and therefore we need to provide the session when reading it.
-var chatHistoryProvider = agent.GetService<VectorChatHistoryProvider>()!;
-Console.WriteLine($"\nSession is stored in vector store under key: {chatHistoryProvider.GetSessionDbKey(resumedSession)}");
-
-namespace SampleApp
-{
-    /// <summary>
-    /// A sample implementation of <see cref="ChatHistoryProvider"/> that stores chat history in a vector store.
-    /// State (the session DB key) is stored in the <see cref="AgentSession.StateBag"/> so it roundtrips
-    /// automatically with session serialization.
-    /// </summary>
-    internal sealed class VectorChatHistoryProvider : ChatHistoryProvider
-    {
-        private readonly ProviderSessionState<State> _sessionState;
-        private IReadOnlyList<string>? _stateKeys;
-        private readonly VectorStore _vectorStore;
-
-        public VectorChatHistoryProvider(
-            VectorStore vectorStore,
-            Func<AgentSession?, State>? stateInitializer = null,
-            string? stateKey = null)
-        {
-            this._sessionState = new ProviderSessionState<State>(
-                stateInitializer ?? (_ => new State(Guid.NewGuid().ToString("N"))),
-                stateKey ?? this.GetType().Name);
-            this._vectorStore = vectorStore ?? throw new ArgumentNullException(nameof(vectorStore));
-        }
-
-        public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey];
-
-        public string GetSessionDbKey(AgentSession session)
-            => this._sessionState.GetOrInitializeState(session).SessionDbKey;
-
-        protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(InvokingContext context, CancellationToken cancellationToken = default)
-        {
-            var state = this._sessionState.GetOrInitializeState(context.Session);
-            var collection = this._vectorStore.GetCollection<string, ChatHistoryItem>("ChatHistory");
-            await collection.EnsureCollectionExistsAsync(cancellationToken);
-
-            var records = await collection
-                .GetAsync(
-                    x => x.SessionId == state.SessionDbKey, 10,
-                    new() { OrderBy = x => x.Descending(y => y.Timestamp) },
-                    cancellationToken)
-                .ToListAsync(cancellationToken);
-
-            var messages = records.ConvertAll(x => JsonSerializer.Deserialize<ChatMessage>(x.SerializedMessage!)!);
-            messages.Reverse();
-            return messages;
-        }
-
-        protected override async ValueTask StoreChatHistoryAsync(InvokedContext context, CancellationToken cancellationToken = default)
-        {
-            var state = this._sessionState.GetOrInitializeState(context.Session);
-
-            var collection = this._vectorStore.GetCollection<string, ChatHistoryItem>("ChatHistory");
-            await collection.EnsureCollectionExistsAsync(cancellationToken);
-
-            var allNewMessages = context.RequestMessages.Concat(context.ResponseMessages ?? []);
-
-            await collection.UpsertAsync(allNewMessages.Select(x => new ChatHistoryItem()
-            {
-                Key = state.SessionDbKey + x.MessageId,
-                Timestamp = DateTimeOffset.UtcNow,
-                SessionId = state.SessionDbKey,
-                SerializedMessage = JsonSerializer.Serialize(x),
-                MessageText = x.Text
-            }), cancellationToken);
-        }
-
-        /// <summary>
-        /// Represents the per-session state stored in the <see cref="AgentSession.StateBag"/>.
-        /// </summary>
-        public sealed class State
-        {
-            public State(string sessionDbKey)
-            {
-                this.SessionDbKey = sessionDbKey ?? throw new ArgumentNullException(nameof(sessionDbKey));
-            }
-
-            public string SessionDbKey { get; }
-        }
-
-        /// <summary>
-        /// The data structure used to store chat history items in the vector store.
-        /// </summary>
-        private sealed class ChatHistoryItem
-        {
-            [VectorStoreKey]
-            public string? Key { get; set; }
-
-            [VectorStoreData]
-            public string? SessionId { get; set; }
-
-            [VectorStoreData]
-            public DateTimeOffset? Timestamp { get; set; }
-
-            [VectorStoreData]
-            public string? SerializedMessage { get; set; }
-
-            [VectorStoreData]
-            public string? MessageText { get; set; }
-        }
-    }
-}

dotnet/samples/02-agents/Agents/Agent_Step13_ChatReduction/Program.cs

@@ -1,72 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to use a chat history reducer to keep the context within model size limits.
-// Any implementation of Microsoft.Extensions.AI.IChatReducer can be used to customize how the chat history is reduced.
-// NOTE: this feature is only supported where the chat history is stored locally, such as with OpenAI Chat Completion.
-// Where the chat history is stored server side, such as with Azure Foundry Agents, the service must manage the chat history size.
-
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using OpenAI.Chat;
-
-var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-// Construct the agent, and provide a factory to create an in-memory chat message store with a reducer that keeps only the last 2 non-system messages.
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent(new ChatClientAgentOptions
-    {
-        ChatOptions = new() { Instructions = "You are good at telling jokes." },
-        Name = "Joker",
-        ChatHistoryProvider = new InMemoryChatHistoryProvider(new() { ChatReducer = new MessageCountingChatReducer(2) })
-    });
-
-AgentSession session = await agent.CreateSessionAsync();
-
-// Invoke the agent and output the text result.
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
-
-// Get the chat history to see how many messages are stored.
-// We can use the ChatHistoryProvider, that is also used by the agent, to read the
-// chat history from the session state, and see how the reducer is affecting the stored messages.
-// Here we expect to see 2 messages, the original user message and the agent response message.
-if (session.TryGetInMemoryChatHistory(out var chatHistory))
-{
-    Console.WriteLine($"\nChat history has {chatHistory.Count} messages.\n");
-}
-
-// Invoke the agent a few more times.
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a robot.", session));
-
-// Now we expect to see 4 messages in the chat history, 2 input and 2 output.
-// While the target number of messages is 2, the default time for the InMemoryChatHistoryProvider
-// to trigger the reducer is just before messages are contributed to a new agent run.
-// So at this time, we have not yet triggered the reducer for the most recently added messages,
-// and they are still in the chat history.
-if (session.TryGetInMemoryChatHistory(out chatHistory))
-{
-    Console.WriteLine($"\nChat history has {chatHistory.Count} messages.\n");
-}
-
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a lemur.", session));
-if (session.TryGetInMemoryChatHistory(out chatHistory))
-{
-    Console.WriteLine($"\nChat history has {chatHistory.Count} messages.\n");
-}
-
-// At this point, the chat history has exceeded the limit and the original message will not exist anymore,
-// so asking a follow up question about it may not work as expected.
-Console.WriteLine(await agent.RunAsync("What was the first joke I asked you to tell again?", session));
-
-if (session.TryGetInMemoryChatHistory(out chatHistory))
-{
-    Console.WriteLine($"\nChat history has {chatHistory.Count} messages.\n");
-}

dotnet/samples/02-agents/Agents/Agent_Step16_Declarative/Agent_Step16_Declarative.csproj

@@ -1,25 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
-    <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
-    <PackageReference Include="Microsoft.Agents.ObjectModel" />
-    <PackageReference Include="Microsoft.Agents.ObjectModel.Json" />
-    <PackageReference Include="Microsoft.Agents.ObjectModel.PowerFx" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Declarative\Microsoft.Agents.AI.Declarative.csproj" />
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
-  </ItemGroup>
-
-</Project>

dotnet/samples/02-agents/Agents/Agent_Step17_AdditionalAIContext/Program.cs

@@ -1,167 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to inject additional AI context into a ChatClientAgent using custom AIContextProvider components that are attached to the agent.
-// Multiple providers can be attached to an agent, and they will be called in sequence, each receiving the accumulated context from the previous one.
-// This mechanism can be used for various purposes, such as injecting RAG search results or memories into the agent's context.
-// Also note that Agent Framework already provides built-in AIContextProviders for many of these scenarios.
-
-#pragma warning disable CA1869 // Cache and reuse 'JsonSerializerOptions' instances
-
-using System.Text;
-using System.Text.Json;
-using Azure.AI.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using OpenAI.Chat;
-using SampleApp;
-using MEAI = Microsoft.Extensions.AI;
-
-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-5-mini";
-
-// A sample function to load the next three calendar events for the user.
-Func<Task<string[]>> loadNextThreeCalendarEvents = async () =>
-{
-    // In a real implementation, this method would connect to a calendar service
-    return new string[]
-    {
-        "Doctor's appointment today at 15:00",
-        "Team meeting today at 17:00",
-        "Birthday party today at 20:00"
-    };
-};
-
-// Create an agent with an AI context provider attached that aggregates two other providers:
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIAgent agent = new AzureOpenAIClient(
-    new Uri(endpoint),
-    new DefaultAzureCredential())
-    .GetChatClient(deploymentName)
-    .AsAIAgent(new ChatClientAgentOptions()
-    {
-        ChatOptions = new() { Instructions = """
-        You are a helpful personal assistant.
-        You manage a TODO list for the user. When the user has completed one of the tasks it can be removed from the TODO list. Only provide the list of TODO items if asked.
-        You remind users of upcoming calendar events when the user interacts with you.
-        """ },
-        ChatHistoryProvider = new InMemoryChatHistoryProvider(new InMemoryChatHistoryProviderOptions
-        {
-            // Use StorageInputRequestMessageFilter to provide a custom filter for request messages stored in chat history.
-            // By default the chat history provider will store all messages, except for those that came from chat history in the first place.
-            // In this case, we want to also exclude messages that came from AI context providers.
-            // You may want to store these messages, depending on their content and your requirements.
-            StorageInputRequestMessageFilter = messages => messages.Where(m => m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.AIContextProvider && m.GetAgentRequestMessageSourceType() != AgentRequestMessageSourceType.ChatHistory)
-        }),
-        // Add multiple AI context providers: one that maintains a todo list and one that provides upcoming calendar entries.
-        // The agent will call each provider in sequence, accumulating context from each.
-        AIContextProviders = [
-            new TodoListAIContextProvider(),
-            new CalendarSearchAIContextProvider(loadNextThreeCalendarEvents)
-        ],
-    });
-
-// Invoke the agent and output the text result.
-AgentSession session = await agent.CreateSessionAsync();
-Console.WriteLine(await agent.RunAsync("I need to pick up milk from the supermarket.", session) + "\n");
-Console.WriteLine(await agent.RunAsync("I need to take Sally for soccer practice.", session) + "\n");
-Console.WriteLine(await agent.RunAsync("I need to make a dentist appointment for Jimmy.", session) + "\n");
-Console.WriteLine(await agent.RunAsync("I've taken Sally to soccer practice.", session) + "\n");
-
-// We can serialize the session, and it will contain both the chat history and the data that each AI context provider serialized.
-JsonElement serializedSession = await agent.SerializeSessionAsync(session);
-// Let's print it to console to show the contents.
-Console.WriteLine(JsonSerializer.Serialize(serializedSession, options: new JsonSerializerOptions() { WriteIndented = true, IndentSize = 2 }) + "\n");
-// The serialized session can be stored long term in a persistent store, but in this case we will just deserialize again and continue the conversation.
-session = await agent.DeserializeSessionAsync(serializedSession);
-
-Console.WriteLine(await agent.RunAsync("Considering my appointments, can you create a plan for my day that plans out when I should complete the items on my todo list?", session) + "\n");
-
-namespace SampleApp
-{
-    /// <summary>
-    /// An <see cref="AIContextProvider"/>, which maintains a todo list for the agent.
-    /// </summary>
-    internal sealed class TodoListAIContextProvider : AIContextProvider
-    {
-        private static List<string> GetTodoItems(AgentSession? session)
-            => session?.StateBag.GetValue<List<string>>(nameof(TodoListAIContextProvider)) ?? new List<string>();
-
-        private static void SetTodoItems(AgentSession? session, List<string> items)
-            => session?.StateBag.SetValue(nameof(TodoListAIContextProvider), items);
-
-        protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
-        {
-            var todoItems = GetTodoItems(context.Session);
-
-            StringBuilder outputMessageBuilder = new();
-            outputMessageBuilder.AppendLine("Your todo list contains the following items:");
-
-            if (todoItems.Count == 0)
-            {
-                outputMessageBuilder.AppendLine("  (no items)");
-            }
-            else
-            {
-                for (int i = 0; i < todoItems.Count; i++)
-                {
-                    outputMessageBuilder.AppendLine($"{i}. {todoItems[i]}");
-                }
-            }
-
-            return new ValueTask<AIContext>(new AIContext
-            {
-                Tools =
-                [
-                    AIFunctionFactory.Create((string item) => AddTodoItem(context.Session, item), "AddTodoItem", "Adds an item to the todo list."),
-                    AIFunctionFactory.Create((int index) => RemoveTodoItem(context.Session, index), "RemoveTodoItem", "Removes an item from the todo list. Index is zero based.")
-                ],
-                Messages =
-                [
-                    new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString())
-                ]
-            });
-        }
-
-        private static void RemoveTodoItem(AgentSession? session, int index)
-        {
-            var items = GetTodoItems(session);
-            items.RemoveAt(index);
-            SetTodoItems(session, items);
-        }
-
-        private static void AddTodoItem(AgentSession? session, string item)
-        {
-            if (string.IsNullOrWhiteSpace(item))
-            {
-                throw new ArgumentException("Item must have a value");
-            }
-
-            var items = GetTodoItems(session);
-            items.Add(item);
-            SetTodoItems(session, items);
-        }
-    }
-
-    /// <summary>
-    /// A <see cref="MessageAIContextProvider"/> which searches for upcoming calendar events and adds them to the AI context.
-    /// </summary>
-    internal sealed class CalendarSearchAIContextProvider(Func<Task<string[]>> loadNextThreeCalendarEvents) : MessageAIContextProvider
-    {
-        protected override async ValueTask<IEnumerable<MEAI.ChatMessage>> ProvideMessagesAsync(InvokingContext context, CancellationToken cancellationToken = default)
-        {
-            var events = await loadNextThreeCalendarEvents();
-
-            StringBuilder outputMessageBuilder = new();
-            outputMessageBuilder.AppendLine("You have the following upcoming calendar events:");
-            foreach (var calendarEvent in events)
-            {
-                outputMessageBuilder.AppendLine($" - {calendarEvent}");
-            }
-
-            return [new MEAI.ChatMessage(ChatRole.User, outputMessageBuilder.ToString())];
-        }
-    }
-}

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming/Program.cs

@@ -1,100 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to use Azure AI Foundry's Red Teaming service to assess
-// the safety and resilience of an AI model against adversarial attacks.
-//
-// It uses the RedTeam API from Azure.AI.Projects to run automated attack simulations
-// with various attack strategies (encoding, obfuscation, jailbreaks) across multiple
-// risk categories (Violence, HateUnfairness, Sexual, SelfHarm).
-//
-// For more details, see:
-// https://learn.microsoft.com/azure/ai-foundry/concepts/ai-red-teaming-agent
-
-using Azure.AI.Projects;
-using Azure.Identity;
-
-string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-Console.WriteLine("=" + new string('=', 79));
-Console.WriteLine("RED TEAMING EVALUATION SAMPLE");
-Console.WriteLine("=" + new string('=', 79));
-Console.WriteLine();
-
-// Initialize Azure credentials and clients
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-DefaultAzureCredential credential = new();
-AIProjectClient aiProjectClient = new(new Uri(endpoint), credential);
-
-// Configure the target model for red teaming
-AzureOpenAIModelConfiguration targetConfig = new(deploymentName);
-
-// Create the red team run configuration
-RedTeam redTeamConfig = new(targetConfig)
-{
-    DisplayName = "FinancialAdvisor-RedTeam",
-    ApplicationScenario = "A financial advisor assistant that provides general financial advice and information.",
-    NumTurns = 3,
-    RiskCategories =
-    {
-        RiskCategory.Violence,
-        RiskCategory.HateUnfairness,
-        RiskCategory.Sexual,
-        RiskCategory.SelfHarm,
-    },
-    AttackStrategies =
-    {
-        AttackStrategy.Easy,
-        AttackStrategy.Moderate,
-        AttackStrategy.Jailbreak,
-    },
-};
-
-Console.WriteLine($"Target model: {deploymentName}");
-Console.WriteLine("Risk categories: Violence, HateUnfairness, Sexual, SelfHarm");
-Console.WriteLine("Attack strategies: Easy, Moderate, Jailbreak");
-Console.WriteLine($"Simulation turns: {redTeamConfig.NumTurns}");
-Console.WriteLine();
-
-// Submit the red team run to the service
-Console.WriteLine("Submitting red team run...");
-RedTeam redTeamRun = await aiProjectClient.RedTeams.CreateAsync(redTeamConfig, options: null);
-
-Console.WriteLine($"Red team run created: {redTeamRun.Name}");
-Console.WriteLine($"Status: {redTeamRun.Status}");
-Console.WriteLine();
-
-// Poll for completion
-Console.WriteLine("Waiting for red team run to complete (this may take several minutes)...");
-while (redTeamRun.Status != "Completed" && redTeamRun.Status != "Failed" && redTeamRun.Status != "Canceled")
-{
-    await Task.Delay(TimeSpan.FromSeconds(15));
-    redTeamRun = await aiProjectClient.RedTeams.GetAsync(redTeamRun.Name);
-    Console.WriteLine($"  Status: {redTeamRun.Status}");
-}
-
-Console.WriteLine();
-
-if (redTeamRun.Status == "Completed")
-{
-    Console.WriteLine("Red team run completed successfully!");
-    Console.WriteLine();
-    Console.WriteLine("Results:");
-    Console.WriteLine(new string('-', 80));
-    Console.WriteLine($"  Run name:    {redTeamRun.Name}");
-    Console.WriteLine($"  Display name: {redTeamRun.DisplayName}");
-    Console.WriteLine($"  Status:      {redTeamRun.Status}");
-
-    Console.WriteLine();
-    Console.WriteLine("Review the detailed results in the Azure AI Foundry portal:");
-    Console.WriteLine($"  {endpoint}");
-}
-else
-{
-    Console.WriteLine($"Red team run ended with status: {redTeamRun.Status}");
-}
-
-Console.WriteLine();
-Console.WriteLine(new string('=', 80));

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming/README.md

@@ -1,101 +0,0 @@
-# Red Teaming with Azure AI Foundry (Classic)
-
-> [!IMPORTANT]
-> This sample uses the **classic Azure AI Foundry** red teaming API (`/redTeams/runs`) via `Azure.AI.Projects`. Results are viewable in the classic Foundry portal experience. The **new Foundry** portal's red teaming feature uses a different evaluation-based API that is not yet available in the .NET SDK.
-
-This sample demonstrates how to use Azure AI Foundry's Red Teaming service to assess the safety and resilience of an AI model against adversarial attacks.
-
-## What this sample demonstrates
-
-- Configuring a red team run targeting an Azure OpenAI model deployment
-- Using multiple `AttackStrategy` options (Easy, Moderate, Jailbreak)
-- Evaluating across `RiskCategory` categories (Violence, HateUnfairness, Sexual, SelfHarm)
-- Submitting a red team scan and polling for completion
-- Reviewing results in the Azure AI Foundry portal
-
-## Prerequisites
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 10 SDK or later
-- Azure AI Foundry project (hub and project created)
-- Azure OpenAI deployment (e.g., gpt-4o or gpt-4o-mini)
-- Azure CLI installed and authenticated (for Azure credential authentication)
-
-### Regional Requirements
-
-Red teaming is only available in regions that support risk and safety evaluators:
-- **East US 2**, **Sweden Central**, **US North Central**, **France Central**, **Switzerland West**
-
-### Environment Variables
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api/projects/your-project" # Replace with your Azure Foundry project endpoint
-$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
-```
-
-## Run the sample
-
-Navigate to the sample directory and run:
-
-```powershell
-cd dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step01_RedTeaming
-dotnet run
-```
-
-## Expected behavior
-
-The sample will:
-
-1. Configure a `RedTeam` run targeting the specified model deployment
-2. Define risk categories and attack strategies
-3. Submit the scan to Azure AI Foundry's Red Teaming service
-4. Poll for completion (this may take several minutes)
-5. Display the run status and direct you to the Azure AI Foundry portal for detailed results
-
-## Understanding Red Teaming
-
-### Attack Strategies
-
-| Strategy | Description |
-|----------|-------------|
-| Easy | Simple encoding/obfuscation attacks (ROT13, Leetspeak, etc.) |
-| Moderate | Moderate complexity attacks requiring an LLM for orchestration |
-| Jailbreak | Crafted prompts designed to bypass AI safeguards (UPIA) |
-
-### Risk Categories
-
-| Category | Description |
-|----------|-------------|
-| Violence | Content related to violence |
-| HateUnfairness | Hate speech or unfair content |
-| Sexual | Sexual content |
-| SelfHarm | Self-harm related content |
-
-### Interpreting Results
-
-- Results are available in the Azure AI Foundry portal (**classic view** — toggle at top-right) under the red teaming section
-- Lower Attack Success Rate (ASR) is better — target ASR < 5% for production
-- Review individual attack conversations to understand vulnerabilities
-
-### Current Limitations
-
-> [!NOTE]
-> - The .NET Red Teaming API (`Azure.AI.Projects`) currently supports targeting **model deployments only** via `AzureOpenAIModelConfiguration`. The `AzureAIAgentTarget` type exists in the SDK but is consumed by the **Evaluation Taxonomy** API (`/evaluationtaxonomies`), not by the Red Teaming API (`/redTeams/runs`).
-> - Agent-targeted red teaming with agent-specific risk categories (Prohibited actions, Sensitive data leakage, Task adherence) is documented in the [concept docs](https://learn.microsoft.com/azure/ai-foundry/concepts/ai-red-teaming-agent) but is not yet available via the public REST API or .NET SDK.
-> - Results from this API appear in the **classic** Azure AI Foundry portal view. The new Foundry portal uses a separate evaluation-based system with `eval_*` identifiers.
-
-## Related Resources
-
-- [Azure AI Red Teaming Agent](https://learn.microsoft.com/azure/ai-foundry/concepts/ai-red-teaming-agent)
-- [RedTeam .NET API Reference](https://learn.microsoft.com/dotnet/api/azure.ai.projects.redteam?view=azure-dotnet-preview)
-- [Risk and Safety Evaluations](https://learn.microsoft.com/azure/ai-foundry/concepts/evaluation-metrics-built-in#risk-and-safety-evaluators)
-
-## Next Steps
-
-After running red teaming:
-1. Review attack results and strengthen agent guardrails
-2. Explore the Self-Reflection sample (FoundryAgents_Evaluations_Step02_SelfReflection) for quality assessment
-3. Set up continuous red teaming in your CI/CD pipeline

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/FoundryAgents_Evaluations_Step02_SelfReflection.csproj

@@ -1,25 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Azure.AI.OpenAI" />
-    <PackageReference Include="Azure.AI.Projects" />
-    <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Microsoft.Extensions.AI.Evaluation" />
-    <PackageReference Include="Microsoft.Extensions.AI.Evaluation.Quality" />
-    <PackageReference Include="Microsoft.Extensions.AI.Evaluation.Safety" />
-    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
-  </ItemGroup>
-
-</Project>

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/Program.cs

@@ -1,292 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample demonstrates how to use Microsoft.Extensions.AI.Evaluation.Quality to evaluate
-// an Agent Framework agent's response quality with a self-reflection loop.
-//
-// It uses GroundednessEvaluator, RelevanceEvaluator, and CoherenceEvaluator to score responses,
-// then iteratively asks the agent to improve based on evaluation feedback.
-//
-// Based on: Reflexion: Language Agents with Verbal Reinforcement Learning (NeurIPS 2023)
-// Reference: https://arxiv.org/abs/2303.11366
-//
-// For more details, see:
-// https://learn.microsoft.com/dotnet/ai/evaluation/libraries
-
-using Azure.AI.OpenAI;
-using Azure.AI.Projects;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using Microsoft.Extensions.AI.Evaluation;
-using Microsoft.Extensions.AI.Evaluation.Quality;
-using Microsoft.Extensions.AI.Evaluation.Safety;
-
-using ChatMessage = Microsoft.Extensions.AI.ChatMessage;
-using ChatRole = Microsoft.Extensions.AI.ChatRole;
-
-string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-string openAiEndpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
-string evaluatorDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? deploymentName;
-
-Console.WriteLine("=" + new string('=', 79));
-Console.WriteLine("SELF-REFLECTION EVALUATION SAMPLE");
-Console.WriteLine("=" + new string('=', 79));
-Console.WriteLine();
-
-// Initialize Azure credentials and client
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-DefaultAzureCredential credential = new();
-AIProjectClient aiProjectClient = new(new Uri(endpoint), credential);
-
-// Set up the LLM-based chat client for quality evaluators
-IChatClient chatClient = new AzureOpenAIClient(new Uri(openAiEndpoint), credential)
-    .GetChatClient(evaluatorDeploymentName)
-    .AsIChatClient();
-
-// Configure evaluation: quality evaluators use the LLM, safety evaluators use Azure AI Foundry
-ContentSafetyServiceConfiguration safetyConfig = new(
-    credential: credential,
-    endpoint: new Uri(endpoint));
-
-ChatConfiguration chatConfiguration = safetyConfig.ToChatConfiguration(
-    originalChatConfiguration: new ChatConfiguration(chatClient));
-
-// Create a test agent
-AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
-    name: "KnowledgeAgent",
-    model: deploymentName,
-    instructions: "You are a helpful assistant. Answer questions accurately based on the provided context.");
-Console.WriteLine($"Created agent: {agent.Name}");
-Console.WriteLine();
-
-// Example question and grounding context
-const string Question = """
-    What are the main benefits of using Azure AI Foundry for building AI applications?
-    """;
-
-const string Context = """
-    Azure AI Foundry is a comprehensive platform for building, deploying, and managing AI applications.
-    Key benefits include:
-    1. Unified development environment with support for multiple AI frameworks and models
-    2. Built-in safety and security features including content filtering and red teaming tools
-    3. Scalable infrastructure that handles deployment and monitoring automatically
-    4. Integration with Azure services like Azure OpenAI, Cognitive Services, and Machine Learning
-    5. Evaluation tools for assessing model quality, safety, and performance
-    6. Support for RAG (Retrieval-Augmented Generation) patterns with vector search
-    7. Enterprise-grade compliance and governance features
-    """;
-
-Console.WriteLine("Question:");
-Console.WriteLine(Question);
-Console.WriteLine();
-
-// Run evaluations
-try
-{
-    await RunSelfReflectionWithGroundedness(agent, Question, Context, chatConfiguration);
-    await RunQualityEvaluation(agent, Question, Context, chatConfiguration);
-    await RunCombinedQualityAndSafetyEvaluation(agent, Question, chatConfiguration);
-}
-finally
-{
-    // Cleanup
-    await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);
-    Console.WriteLine();
-    Console.WriteLine("Cleanup: Agent deleted.");
-}
-
-// ============================================================================
-// Implementation Functions
-// ============================================================================
-
-static async Task RunSelfReflectionWithGroundedness(
-    AIAgent agent, string question, string context, ChatConfiguration chatConfiguration)
-{
-    Console.WriteLine("Running Self-Reflection with Groundedness Evaluation...");
-    Console.WriteLine();
-
-    GroundednessEvaluator groundednessEvaluator = new();
-    GroundednessEvaluatorContext groundingContext = new(context);
-
-    const int MaxReflections = 3;
-    double bestScore = 0;
-
-    string currentPrompt = $"Context: {context}\n\nQuestion: {question}";
-
-    for (int i = 0; i < MaxReflections; i++)
-    {
-        Console.WriteLine($"Iteration {i + 1}/{MaxReflections}:");
-        Console.WriteLine(new string('-', 40));
-
-        // Create a new session for each reflection iteration so that
-        // conversation context does not carry over between runs. This keeps
-        // each evaluation independent and avoids biasing groundedness scores.
-        AgentSession session = await agent.CreateSessionAsync();
-        AgentResponse agentResponse = await agent.RunAsync(currentPrompt, session);
-        string responseText = agentResponse.Text;
-
-        Console.WriteLine($"Response: {responseText[..Math.Min(150, responseText.Length)]}...");
-
-        List<ChatMessage> messages =
-        [
-            new(ChatRole.User, currentPrompt),
-        ];
-        ChatResponse chatResponse = new(new ChatMessage(ChatRole.Assistant, responseText));
-
-        EvaluationResult result = await groundednessEvaluator.EvaluateAsync(
-            messages,
-            chatResponse,
-            chatConfiguration,
-            additionalContext: [groundingContext]);
-
-        NumericMetric groundedness = result.Get<NumericMetric>(GroundednessEvaluator.GroundednessMetricName);
-        double score = groundedness.Value ?? 0;
-        string rating = groundedness.Interpretation?.Rating.ToString() ?? "N/A";
-
-        Console.WriteLine($"Groundedness score: {score:F1}/5 (Rating: {rating})");
-        Console.WriteLine();
-
-        if (score > bestScore)
-        {
-            bestScore = score;
-        }
-
-        if (score >= 4.0 || i == MaxReflections - 1)
-        {
-            if (score >= 4.0)
-            {
-                Console.WriteLine("Good groundedness achieved!");
-            }
-
-            break;
-        }
-
-        // Ask for improvement in the next iteration, including the previous response
-        // so the LLM knows what to improve on (each iteration uses a new session).
-        currentPrompt = $"""
-            Context: {context}
-
-            Your previous answer scored {score}/5 on groundedness.
-            Your previous answer was:
-            {responseText}
-
-            Please improve your answer to be more grounded in the provided context.
-            Only include information that is directly supported by the context.
-
-            Question: {question}
-            """;
-        Console.WriteLine("Requesting improvement...");
-        Console.WriteLine();
-    }
-
-    Console.WriteLine($"Best groundedness score: {bestScore:F1}/5");
-    Console.WriteLine(new string('=', 80));
-    Console.WriteLine();
-}
-
-static async Task RunQualityEvaluation(
-    AIAgent agent, string question, string context, ChatConfiguration chatConfiguration)
-{
-    Console.WriteLine("Running Quality Evaluation (Relevance, Coherence, Groundedness)...");
-    Console.WriteLine();
-
-    IEvaluator[] evaluators =
-    [
-        new RelevanceEvaluator(),
-        new CoherenceEvaluator(),
-        new GroundednessEvaluator(),
-    ];
-
-    CompositeEvaluator compositeEvaluator = new(evaluators);
-    GroundednessEvaluatorContext groundingContext = new(context);
-
-    string prompt = $"Context: {context}\n\nQuestion: {question}";
-
-    AgentSession session = await agent.CreateSessionAsync();
-    AgentResponse agentResponse = await agent.RunAsync(prompt, session);
-    string responseText = agentResponse.Text;
-
-    Console.WriteLine($"Response: {responseText[..Math.Min(150, responseText.Length)]}...");
-    Console.WriteLine();
-
-    List<ChatMessage> messages =
-    [
-        new(ChatRole.User, prompt),
-    ];
-    ChatResponse chatResponse = new(new ChatMessage(ChatRole.Assistant, responseText));
-
-    EvaluationResult result = await compositeEvaluator.EvaluateAsync(
-        messages,
-        chatResponse,
-        chatConfiguration,
-        additionalContext: [groundingContext]);
-
-    foreach (EvaluationMetric metric in result.Metrics.Values)
-    {
-        if (metric is NumericMetric n)
-        {
-            string rating = n.Interpretation?.Rating.ToString() ?? "N/A";
-            Console.WriteLine($"  {n.Name,-20} Score: {n.Value:F1}/5  Rating: {rating}");
-        }
-    }
-
-    Console.WriteLine(new string('=', 80));
-    Console.WriteLine();
-}
-
-static async Task RunCombinedQualityAndSafetyEvaluation(
-    AIAgent agent, string question, ChatConfiguration chatConfiguration)
-{
-    Console.WriteLine("Running Combined Quality + Safety Evaluation...");
-    Console.WriteLine();
-
-    IEvaluator[] evaluators =
-    [
-        new RelevanceEvaluator(),
-        new CoherenceEvaluator(),
-        new ContentHarmEvaluator(),
-        new ProtectedMaterialEvaluator(),
-    ];
-
-    CompositeEvaluator compositeEvaluator = new(evaluators);
-
-    AgentSession session = await agent.CreateSessionAsync();
-    AgentResponse agentResponse = await agent.RunAsync(question, session);
-    string responseText = agentResponse.Text;
-
-    Console.WriteLine($"Response: {responseText[..Math.Min(150, responseText.Length)]}...");
-    Console.WriteLine();
-
-    List<ChatMessage> messages =
-    [
-        new(ChatRole.User, question), // No context in this evaluation — testing quality and safety on raw question
-    ];
-    ChatResponse chatResponse = new(new ChatMessage(ChatRole.Assistant, responseText));
-
-    EvaluationResult result = await compositeEvaluator.EvaluateAsync(
-        messages,
-        chatResponse,
-        chatConfiguration);
-
-    Console.WriteLine("Quality Metrics:");
-    foreach (EvaluationMetric metric in result.Metrics.Values)
-    {
-        if (metric is NumericMetric n)
-        {
-            string rating = n.Interpretation?.Rating.ToString() ?? "N/A";
-            bool failed = n.Interpretation?.Failed ?? false;
-            Console.WriteLine($"  {n.Name,-25} Score: {n.Value:F1,-6} Rating: {rating,-15} Failed: {failed}");
-        }
-        else if (metric is BooleanMetric b)
-        {
-            string rating = b.Interpretation?.Rating.ToString() ?? "N/A";
-            bool failed = b.Interpretation?.Failed ?? false;
-            Console.WriteLine($"  {b.Name,-25} Value: {b.Value,-6} Rating: {rating,-15} Failed: {failed}");
-        }
-    }
-
-    Console.WriteLine(new string('=', 80));
-}

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection/README.md

@@ -1,118 +0,0 @@
-# Self-Reflection Evaluation with Groundedness Assessment
-
-This sample demonstrates the self-reflection pattern using Agent Framework with `Microsoft.Extensions.AI.Evaluation.Quality` evaluators. The agent iteratively improves its responses based on real groundedness evaluation scores.
-
-For details on the self-reflection approach, see [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366) (NeurIPS 2023).
-
-## What this sample demonstrates
-
-- Self-reflection loop that improves responses using real `GroundednessEvaluator` scores
-- Using `RelevanceEvaluator` and `CoherenceEvaluator` for multi-metric quality assessment
-- Combining quality and safety evaluators with `CompositeEvaluator`
-- Configuring `ContentSafetyServiceConfiguration` for safety evaluators alongside LLM-based quality evaluators
-- Tracking improvement across iterations
-
-## Prerequisites
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 10 SDK or later
-- Azure AI Foundry project (hub and project created)
-- Azure OpenAI deployment (e.g., gpt-4o or gpt-4o-mini)
-- Azure CLI installed and authenticated (for Azure credential authentication)
-
-**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
-
-### Azure Resources Required
-
-1. **Azure AI Hub and Project**: Create these in the Azure Portal
-   - Follow: https://learn.microsoft.com/azure/ai-foundry/how-to/create-projects
-2. **Azure OpenAI Deployment**: Deploy a model (e.g., gpt-4o or gpt-4o-mini)
-   - Agent model: Used to generate responses
-   - Evaluator model: Quality evaluators use an LLM; best results with GPT-4o
-3. **Azure CLI**: Install and authenticate with `az login`
-
-### Environment Variables
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-project.api.azureml.ms"  # Azure Foundry project endpoint
-$env:AZURE_OPENAI_ENDPOINT="https://your-openai.openai.azure.com/"         # Azure OpenAI endpoint (for quality evaluators)
-$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"                   # Model deployment name
-```
-
-**Note**: For best evaluation results, use GPT-4o or GPT-4o-mini as the evaluator model. The groundedness evaluator has been tested and tuned for these models.
-
-## Run the sample
-
-Navigate to the sample directory and run:
-
-```powershell
-cd dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Evaluations_Step02_SelfReflection
-dotnet run
-```
-
-## Expected behavior
-
-The sample runs three evaluation scenarios:
-
-### 1. Self-Reflection with Groundedness
-- Asks a question with grounding context
-- Evaluates response groundedness using `GroundednessEvaluator`
-- If score is below 4/5, asks the agent to improve with feedback
-- Repeats up to 3 iterations
-- Tracks and reports the best score achieved
-
-### 2. Quality Evaluation
-- Evaluates a single response with multiple quality evaluators:
-  - `RelevanceEvaluator` — is the response relevant to the question?
-  - `CoherenceEvaluator` — is the response logically coherent?
-  - `GroundednessEvaluator` — is the response grounded in the provided context?
-
-### 3. Combined Quality + Safety Evaluation
-- Runs both quality and safety evaluators together:
-  - `RelevanceEvaluator`, `CoherenceEvaluator` (quality)
-  - `ContentHarmEvaluator` (safety — violence, hate, sexual, self-harm)
-  - `ProtectedMaterialEvaluator` (safety — copyrighted content detection)
-
-## Understanding the Evaluation
-
-### Groundedness Score (1-5 scale)
-
-The `GroundednessEvaluator` measures how well the agent's response is grounded in the provided context:
-
-- **5** = Excellent - Response is fully grounded in context
-- **4** = Good - Mostly grounded with minor deviations
-- **3** = Fair - Partially grounded but includes unsupported claims
-- **2** = Poor - Significant amount of ungrounded content
-- **1** = Very Poor - Response is largely unsupported by context
-
-### Self-Reflection Process
-
-1. **Initial Response**: Agent generates answer based on question + context
-2. **Evaluation**: `GroundednessEvaluator` scores the response (1-5)
-3. **Feedback**: If score < 4, agent receives the score and is asked to improve
-4. **Iteration**: Process repeats until good score or max iterations
-
-## Best Practices
-
-1. **Provide Complete Context**: Ensure grounding context contains all information needed to answer the question
-2. **Clear Instructions**: Give the agent clear instructions about staying grounded in context
-3. **Use Quality Models**: GPT-4o recommended for evaluation tasks
-4. **Multiple Evaluators**: Use combination of evaluators (groundedness + relevance + coherence)
-5. **Batch Processing**: For production, process multiple questions in batch
-
-## Related Resources
-
-- [Reflexion Paper (NeurIPS 2023)](https://arxiv.org/abs/2303.11366)
-- [Microsoft.Extensions.AI.Evaluation Libraries](https://learn.microsoft.com/dotnet/ai/evaluation/libraries)
-- [GroundednessEvaluator API Reference](https://learn.microsoft.com/dotnet/api/microsoft.extensions.ai.evaluation.quality.groundednessevaluator)
-- [Azure AI Foundry Evaluation Service](https://learn.microsoft.com/azure/ai-foundry/how-to/develop/evaluate-sdk)
-
-## Next Steps
-
-After running self-reflection evaluation:
-1. Implement similar patterns for other quality metrics (relevance, coherence, fluency)
-2. Integrate into CI/CD pipeline for continuous quality assurance
-3. Explore the Safety Evaluation sample (FoundryAgents_Evaluations_Step01_RedTeaming) for content safety assessment

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/Program.cs

@@ -1,55 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to create and use a simple AI agent with a multi-turn conversation.
-
-using Azure.AI.Projects;
-using Azure.AI.Projects.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-
-string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-const string JokerInstructions = "You are good at telling jokes.";
-const string JokerName = "JokerAgent";
-
-// Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
-
-// Define the agent you want to create. (Prompt Agent in this case)
-AgentVersionCreationOptions options = new(new PromptAgentDefinition(model: deploymentName) { Instructions = JokerInstructions });
-
-// Retrieve an AIAgent for the created server side agent version.
-ChatClientAgent jokerAgent = await aiProjectClient.CreateAIAgentAsync(name: JokerName, options);
-
-// Invoke the agent with a multi-turn conversation, where the context is preserved in the session object.
-// Create a conversation in the server
-ProjectConversationsClient conversationsClient = aiProjectClient.GetProjectOpenAIClient().GetProjectConversationsClient();
-ProjectConversation conversation = await conversationsClient.CreateProjectConversationAsync();
-
-// Providing the conversation Id is not strictly necessary, but by not providing it no information will show up in the Foundry Project UI as conversations.
-// Sessions that don't have a conversation Id will work based on the `PreviousResponseId`.
-AgentSession session = await jokerAgent.CreateSessionAsync(conversation.Id);
-
-Console.WriteLine(await jokerAgent.RunAsync("Tell me a joke about a pirate.", session));
-Console.WriteLine(await jokerAgent.RunAsync("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", session));
-
-// Invoke the agent with a multi-turn conversation and streaming, where the context is preserved in the session object.
-session = await jokerAgent.CreateSessionAsync(conversation.Id);
-await foreach (AgentResponseUpdate update in jokerAgent.RunStreamingAsync("Tell me a joke about a pirate.", session))
-{
-    Console.WriteLine(update);
-}
-await foreach (AgentResponseUpdate update in jokerAgent.RunStreamingAsync("Now add some emojis to the joke and tell it in the voice of a pirate's parrot.", session))
-{
-    Console.WriteLine(update);
-}
-
-// Cleanup by agent name removes the agent version created.
-await aiProjectClient.Agents.DeleteAgentAsync(jokerAgent.Name);
-
-// Cleanup the conversation created.
-await conversationsClient.DeleteConversationAsync(conversation.Id);

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Step02_MultiturnConversation/README.md

@@ -1,59 +0,0 @@
-# Multi-turn Conversation with AI Agents
-
-This sample demonstrates how to implement multi-turn conversations with AI agents, where context is preserved across multiple agent runs using threads and conversation IDs.
-
-## What this sample demonstrates
-
-- Creating an AI agent with instructions
-- Creating a project conversation to track conversations in the Foundry UI
-- Using threads with conversation IDs to maintain conversation context
-- Running multi-turn conversations with text output
-- Running multi-turn conversations with streaming output
-- Managing agent and conversation lifecycle (creation and deletion)
-
-## Prerequisites
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 10 SDK or later
-- Azure Foundry service endpoint and deployment configured
-- Azure CLI installed and authenticated (for Azure credential authentication)
-
-**Note**: This demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure CLI documentation](https://learn.microsoft.com/cli/azure/authenticate-azure-cli-interactively).
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
-$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
-```
-
-## Run the sample
-
-Navigate to the FoundryAgents sample directory and run:
-
-```powershell
-cd dotnet/samples/02-agents/FoundryAgents
-dotnet run --project .\FoundryAgents_Step02_MultiturnConversation
-```
-
-## Expected behavior
-
-The sample will:
-
-1. Create an agent named "JokerAgent" with instructions to tell jokes
-2. Create a project conversation to enable visibility in the Azure Foundry UI
-3. Create a thread linked to the conversation ID for context tracking
-4. Run the agent with a text prompt and display the response
-5. Send a follow-up message to the same thread, demonstrating context preservation
-6. Create a new thread sharing the same conversation ID and run the agent with streaming
-7. Send a follow-up streaming message to demonstrate multi-turn streaming
-8. Clean up resources by deleting the agent and conversation
-
-## Conversation ID vs PreviousResponseId
-
-When working with multi-turn conversations, there are two approaches:
-
-- **With Conversation ID**: By passing a `conversation.Id` to `CreateSessionAsync()`, the conversation will be visible in the Azure Foundry Project UI. This is useful for tracking and debugging conversations.
-- **Without Conversation ID**: Sessions created without a conversation ID still work correctly, maintaining context via `PreviousResponseId`. However, these conversations may not appear in the Foundry UI.
-

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Step06_PersistedConversations/Program.cs

@@ -1,47 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to create and use a simple AI agent with a conversation that can be persisted to disk.
-
-using System.Text.Json;
-using Azure.AI.Projects;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-
-string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-const string JokerInstructions = "You are good at telling jokes.";
-const string JokerName = "JokerAgent";
-
-// Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
-
-AIAgent agent = await aiProjectClient.CreateAIAgentAsync(name: JokerName, model: deploymentName, instructions: JokerInstructions);
-
-// Start a new session for the agent conversation.
-AgentSession session = await agent.CreateSessionAsync();
-
-// Run the agent with a new session.
-Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));
-
-// Serialize the session state to a JsonElement, so it can be stored for later use.
-JsonElement serializedSession = await agent.SerializeSessionAsync(session);
-
-// Save the serialized session to a temporary file (for demonstration purposes).
-string tempFilePath = Path.GetTempFileName();
-await File.WriteAllTextAsync(tempFilePath, JsonSerializer.Serialize(serializedSession));
-
-// Load the serialized session from the temporary file (for demonstration purposes).
-JsonElement reloadedSerializedSession = JsonElement.Parse(await File.ReadAllTextAsync(tempFilePath))!;
-
-// Deserialize the session state after loading from storage.
-AgentSession resumedSession = await agent.DeserializeSessionAsync(reloadedSerializedSession);
-
-// Run the agent again with the resumed session.
-Console.WriteLine(await agent.RunAsync("Now tell the same joke in the voice of a pirate, and add some emojis to the joke.", resumedSession));
-
-// Cleanup by agent name removes the agent version created.
-await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Step10_UsingImages/Program.cs

@@ -1,38 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to use Image Multi-Modality with an AI agent.
-
-using Azure.AI.Projects;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
-
-const string VisionInstructions = "You are a helpful agent that can analyze images";
-const string VisionName = "VisionAgent";
-
-// Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
-
-// Define the agent you want to create. (Prompt Agent in this case)
-AIAgent agent = await aiProjectClient.CreateAIAgentAsync(name: VisionName, model: deploymentName, instructions: VisionInstructions);
-
-ChatMessage message = new(ChatRole.User, [
-    new TextContent("What do you see in this image?"),
-    await DataContent.LoadFromAsync("assets/walkway.jpg"),
-]);
-
-AgentSession session = await agent.CreateSessionAsync();
-
-await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(message, session))
-{
-    Console.WriteLine(update);
-}
-
-// Cleanup by agent name removes the agent version created.
-await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Step16_FileSearch/FoundryAgents_Step16_FileSearch.csproj

@@ -1,22 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFrameworks>net10.0</TargetFrameworks>
-
-    <Nullable>enable</Nullable>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <NoWarn>$(NoWarn);CA1812</NoWarn>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Microsoft.Extensions.Logging.Console" />
-    <PackageReference Include="Azure.Identity" />
-    <PackageReference Include="Azure.AI.Projects" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
-  </ItemGroup>
-  
-</Project>

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Step16_FileSearch/Program.cs

@@ -1,111 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-// This sample shows how to use File Search Tool with AI Agents.
-
-using Azure.AI.Projects;
-using Azure.AI.Projects.OpenAI;
-using Azure.Identity;
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-using OpenAI.Assistants;
-using OpenAI.Files;
-using OpenAI.Responses;
-
-string endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
-string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
-
-const string AgentInstructions = "You are a helpful assistant that can search through uploaded files to answer questions.";
-
-// Get a client to create/retrieve/delete server side agents with Azure Foundry Agents.
-// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
-// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
-// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
-AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());
-var projectOpenAIClient = aiProjectClient.GetProjectOpenAIClient();
-var filesClient = projectOpenAIClient.GetProjectFilesClient();
-var vectorStoresClient = projectOpenAIClient.GetProjectVectorStoresClient();
-
-// 1. Create a temp file with test content and upload it.
-string searchFilePath = Path.Combine(Path.GetTempPath(), Path.GetRandomFileName() + "_lookup.txt");
-File.WriteAllText(
-    path: searchFilePath,
-    contents: """
-        Employee Directory:
-        - Alice Johnson, 28 years old, Software Engineer, Engineering Department
-        - Bob Smith, 35 years old, Sales Manager, Sales Department
-        - Carol Williams, 42 years old, HR Director, Human Resources Department
-        - David Brown, 31 years old, Customer Support Lead, Support Department
-        """
-);
-
-Console.WriteLine($"Uploading file: {searchFilePath}");
-OpenAIFile uploadedFile = filesClient.UploadFile(
-    filePath: searchFilePath,
-    purpose: FileUploadPurpose.Assistants
-);
-Console.WriteLine($"Uploaded file, file ID: {uploadedFile.Id}");
-
-// 2. Create a vector store with the uploaded file.
-var vectorStoreResult = await vectorStoresClient.CreateVectorStoreAsync(
-    options: new() { FileIds = { uploadedFile.Id }, Name = "EmployeeDirectory_VectorStore" }
-);
-string vectorStoreId = vectorStoreResult.Value.Id;
-Console.WriteLine($"Created vector store, vector store ID: {vectorStoreId}");
-
-AIAgent agent = await CreateAgentWithMEAI();
-// AIAgent agent = await CreateAgentWithNativeSDK();
-
-// Run the agent
-Console.WriteLine("\n--- Running File Search Agent ---");
-AgentResponse response = await agent.RunAsync("Who is the youngest employee?");
-Console.WriteLine($"Response: {response}");
-
-// Getting any file citation annotations generated by the tool
-foreach (AIAnnotation annotation in response.Messages.SelectMany(m => m.Contents).SelectMany(c => c.Annotations ?? []))
-{
-    if (annotation.RawRepresentation is TextAnnotationUpdate citationAnnotation)
-    {
-        Console.WriteLine($$"""
-            File Citation:
-              File Id: {{citationAnnotation.OutputFileId}}
-              Text to Replace: {{citationAnnotation.TextToReplace}}
-            """);
-    }
-}
-
-// Cleanup.
-Console.WriteLine("\n--- Cleanup ---");
-await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);
-await vectorStoresClient.DeleteVectorStoreAsync(vectorStoreId);
-await filesClient.DeleteFileAsync(uploadedFile.Id);
-File.Delete(searchFilePath);
-Console.WriteLine("Cleanup completed successfully.");
-
-// --- Agent Creation Options ---
-
-#pragma warning disable CS8321 // Local function is declared but never used
-// Option 1 - Using HostedFileSearchTool (MEAI + AgentFramework)
-async Task<AIAgent> CreateAgentWithMEAI()
-{
-    return await aiProjectClient.CreateAIAgentAsync(
-        model: deploymentName,
-        name: "FileSearchAgent-MEAI",
-        instructions: AgentInstructions,
-        tools: [new HostedFileSearchTool() { Inputs = [new HostedVectorStoreContent(vectorStoreId)] }]);
-}
-
-// Option 2 - Using PromptAgentDefinition with ResponseTool.CreateFileSearchTool (Native SDK)
-async Task<AIAgent> CreateAgentWithNativeSDK()
-{
-    return await aiProjectClient.CreateAIAgentAsync(
-        name: "FileSearchAgent-NATIVE",
-        creationOptions: new AgentVersionCreationOptions(
-            new PromptAgentDefinition(model: deploymentName)
-            {
-                Instructions = AgentInstructions,
-                Tools = {
-                    ResponseTool.CreateFileSearchTool(vectorStoreIds: [vectorStoreId])
-                }
-            })
-    );
-}

dotnet/samples/02-agents/FoundryAgents/FoundryAgents_Step16_FileSearch/README.md

@@ -1,52 +0,0 @@
-# Using File Search with AI Agents
-
-This sample demonstrates how to use the file search tool with AI agents. The file search tool allows agents to search through uploaded files stored in vector stores to answer user questions.
-
-## What this sample demonstrates
-
-- Uploading files and creating vector stores
-- Creating agents with file search capabilities
-- Using HostedFileSearchTool (MEAI abstraction)
-- Using native SDK file search tools (ResponseTool.CreateFileSearchTool)
-- Handling file citation annotations
-- Managing agent and resource lifecycle (creation and deletion)
-
-## Prerequisites
-
-Before you begin, ensure you have the following prerequisites:
-
-- .NET 10 SDK or later
-- Azure Foundry service endpoint and deployment configured
-- Azure CLI installed and authenticated (for Azure credential authentication)
-
-**Note**: This demo uses `DefaultAzureCredential` for authentication. For local development, make sure you're logged in with `az login` and have access to the Azure Foundry resource. For more information, see the [Azure Identity documentation](https://learn.microsoft.com/dotnet/api/azure.identity.defaultazurecredential).
-
-Set the following environment variables:
-
-```powershell
-$env:AZURE_AI_PROJECT_ENDPOINT="https://your-foundry-service.services.ai.azure.com/api/projects/your-foundry-project" # Replace with your Azure Foundry resource endpoint
-$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4o-mini"  # Optional, defaults to gpt-4o-mini
-```
-
-## Run the sample
-
-Navigate to the FoundryAgents sample directory and run:
-
-```powershell
-cd dotnet/samples/02-agents/FoundryAgents
-dotnet run --project .\FoundryAgents_Step16_FileSearch
-```
-
-## Expected behavior
-
-The sample will:
-
-1. Create a temporary text file with employee directory information
-2. Upload the file to Azure Foundry
-3. Create a vector store with the uploaded file
-4. Create an agent with file search capabilities using one of:
-   - Option 1: Using HostedFileSearchTool (MEAI abstraction)
-   - Option 2: Using native SDK file search tools
-5. Run a query against the agent to search through the uploaded file
-6. Display file citation annotations from responses
-7. Clean up resources (agent, vector store, and uploaded file)