Updated chatkit package version (#1950)

* Add workflow mix agent executor samples

* Apply suggestion from @Copilot

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

.github/.linkspector.yml

@@ -12,11 +12,14 @@ ignorePatterns:
   - pattern: "https:\/\/platform.openai.com"
   - pattern: "http:\/\/localhost"
   - pattern: "http:\/\/127.0.0.1"
+  - pattern: "https:\/\/localhost"
+  - pattern: "https:\/\/127.0.0.1"
   - pattern: "0001-spec.md"
   - pattern: "0001-madr-architecture-decisions.md"
   - pattern: "https://api.powerplatform.com/.default"
   - pattern: "https://your-resource.openai.azure.com/"
   - pattern: "http://host.docker.internal"
+  - pattern: "https://openai.github.io/openai-agents-js/openai/agents/classes/"
 # excludedDirs:
   # Folders which include links to localhost, since it's not ignored with regular expressions
 baseUrl: https://github.com/microsoft/agent-framework/

.github/upgrades/prompts/SemanticKernelToAgentFramework.md

@@ -1052,7 +1052,7 @@ AgentThread thread = agent.GetNewThread();
 
 **Add Agent Framework Packages:**
 ```xml
-<PackageReference Include="Microsoft.Agents.AI.AzureAI" />
+<PackageReference Include="Microsoft.Agents.AI.AzureAI.Persistent" />
 <PackageReference Include="Azure.Identity" />
 ```
 </configuration_changes>

.github/workflows/codeql-analysis.yml

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

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

@@ -74,6 +74,7 @@ jobs:
             .
             .github
             dotnet
+            python
             workflow-samples
 
       - name: Setup dotnet
@@ -127,7 +128,15 @@ jobs:
         run: |
           export UT_PROJECTS=$(find ./dotnet -type f -name "*.UnitTests.csproj" | tr '\n' ' ')
           for project in $UT_PROJECTS; do
-            dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx --collect:"XPlat Code Coverage" --results-directory:"TestResults/Coverage/" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.ExcludeByAttribute=GeneratedCodeAttribute,CompilerGeneratedAttribute,ExcludeFromCodeCoverageAttribute
+            # Query the project's target frameworks using MSBuild with the current configuration
+            target_frameworks=$(dotnet msbuild $project -getProperty:TargetFrameworks -p:Configuration=${{ matrix.configuration }} -nologo 2>/dev/null | tr -d '\r')
+            
+            # Check if the project supports the target framework
+            if [[ "$target_frameworks" == *"${{ matrix.targetFramework }}"* ]]; then
+              dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx --collect:"XPlat Code Coverage" --results-directory:"TestResults/Coverage/" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.ExcludeByAttribute=GeneratedCodeAttribute,CompilerGeneratedAttribute,ExcludeFromCodeCoverageAttribute
+            else
+              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
+            fi
           done
       
       - name: Log event name and matrix integration-tests
@@ -148,7 +157,15 @@ jobs:
         run: |
           export INTEGRATION_TEST_PROJECTS=$(find ./dotnet -type f -name "*IntegrationTests.csproj" | tr '\n' ' ')
           for project in $INTEGRATION_TEST_PROJECTS; do
-            dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx
+            # Query the project's target frameworks using MSBuild with the current configuration
+            target_frameworks=$(dotnet msbuild $project -getProperty:TargetFrameworks -p:Configuration=${{ matrix.configuration }} -nologo 2>/dev/null | tr -d '\r')
+            
+            # Check if the project supports the target framework
+            if [[ "$target_frameworks" == *"${{ matrix.targetFramework }}"* ]]; then
+              dotnet test -f ${{ matrix.targetFramework }} -c ${{ matrix.configuration }} $project --no-build -v Normal --logger trx
+            else
+              echo "Skipping $project - does not support target framework ${{ matrix.targetFramework }} (supports: $target_frameworks)"
+            fi
           done
         env:
           # OpenAI Models
@@ -166,14 +183,14 @@ jobs:
 
       # Generate test reports and check coverage
       - name: Generate test reports
-        uses: danielpalme/ReportGenerator-GitHub-Action@5.4.16
+        uses: danielpalme/ReportGenerator-GitHub-Action@5.4.18
         with:
           reports: "./TestResults/Coverage/**/coverage.cobertura.xml"
           targetdir: "./TestResults/Reports"
           reporttypes: "HtmlInline;JsonSummary"
 
       - name: Upload coverage report artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: CoverageReport-${{ matrix.os }}-${{ matrix.targetFramework }}-${{ matrix.configuration }} # Artifact name
           path: ./TestResults/Reports # Directory containing files to upload

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

@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.10", "3.14"]
     runs-on: ubuntu-latest
     continue-on-error: true
     defaults:

.github/workflows/python-docs.yml

@@ -26,7 +26,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - name: Set up uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v7
         with:
           version-file: "python/pyproject.toml"
           enable-cache: true

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

@@ -1,27 +1,54 @@
 name: Python - Lab Tests
 
 on:
+  workflow_dispatch:
   pull_request:
-    branches: ["main", "feature*"]
-    paths:
-      - "python/packages/lab/**"
-  push:
     branches: ["main"]
     paths:
       - "python/packages/lab/**"
+  merge_group:
+    branches: ["main"]
+  schedule:
+    - cron: "0 0 * * *" # Run at midnight UTC daily
 
 env:
   # Configure a constant location for the uv cache
   UV_CACHE_DIR: /tmp/.uv-cache
 
 jobs:
+  paths-filter:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      pythonChanges: ${{ steps.filter.outputs.python}}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            python:
+              - 'python/**'
+      # run only if 'python' files were changed
+      - name: python tests
+        if: steps.filter.outputs.python == 'true'
+        run: echo "Python file"
+      # run only if not 'python' files were changed
+      - name: not python tests
+        if: steps.filter.outputs.python != 'true'
+        run: echo "NOT python file"
+
   python-lab-tests:
     name: Python Lab Tests
+    needs: paths-filter
+    if: needs.paths-filter.outputs.pythonChanges == 'true'
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: true
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
         # TODO(ekzhu): re-enable macos-latest when this is fixed: https://github.com/actions/runner-images/issues/11881
         os: [ubuntu-latest, windows-latest]
     env:

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

@@ -43,8 +43,8 @@ jobs:
       - name: not python tests
         if: steps.filter.outputs.python != 'true'
         run: echo "NOT python file"
-  python-tests-main:
-    name: Python Tests - Main
+  python-tests-core:
+    name: Python Tests - Core
     needs: paths-filter
     if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
     runs-on: ${{ matrix.os }}
@@ -60,56 +60,8 @@ jobs:
       OPENAI_CHAT_MODEL_ID: ${{ vars.OPENAI__CHATMODELID }}
       OPENAI_RESPONSES_MODEL_ID: ${{ vars.OPENAI__RESPONSESMODELID }}
       OPENAI_API_KEY: ${{ secrets.OPENAI__APIKEY }}
-      LOCAL_MCP_URL: ${{ vars.LOCAL_MCP__URL }}
-    defaults:
-      run:
-        working-directory: python
-    steps:
-      - uses: actions/checkout@v5
-      - name: Set up python and install the project
-        id: python-setup
-        uses: ./.github/actions/python-setup
-        with:
-          python-version: ${{ matrix.python-version }}
-          os: ${{ runner.os }}
-        env:
-          # Configure a constant location for the uv cache
-          UV_CACHE_DIR: /tmp/.uv-cache
-      - 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 main 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: Test results
-
-  python-tests-azure-ai:
-    name: Python Tests - Azure
-    needs: paths-filter
-    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
-    runs-on: ${{ matrix.os }}
-    environment: ${{ matrix.environment }}
-    strategy:
-      fail-fast: true
-      matrix:
-        python-version: ["3.10"]
-        os: [ubuntu-latest]
-        environment: ["integration"]
-    env:
-      UV_PYTHON: ${{ matrix.python-version }}
-      AZURE_AI_PROJECT_ENDPOINT: ${{ secrets.AZUREAI__ENDPOINT }}
-      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${{ vars.AZUREAI__DEPLOYMENTNAME }}
+      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+      ANTHROPIC_CHAT_MODEL_ID: ${{ vars.ANTHROPIC_CHAT_MODEL_ID }}
       AZURE_OPENAI_CHAT_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__CHATDEPLOYMENTNAME }}
       AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME: ${{ vars.AZUREOPENAI__RESPONSESDEPLOYMENTNAME }}
       AZURE_OPENAI_ENDPOINT: ${{ vars.AZUREOPENAI__ENDPOINT }}
@@ -139,10 +91,67 @@ jobs:
         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 azure samples
+      - name: Test core samples
         timeout-minutes: 10
         if: env.RUN_SAMPLES_TESTS == 'true'
-        run: uv run pytest tests/samples/ -m "azure-ai" -m "azure"
+        run: uv run pytest tests/samples/ -m "openai" -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: Test results
+
+  python-tests-azure-ai:
+    name: Python Tests - Azure AI
+    needs: paths-filter
+    if: github.event_name != 'pull_request' && needs.paths-filter.outputs.pythonChanges == 'true'
+    runs-on: ${{ matrix.os }}
+    environment: ${{ matrix.environment }}
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.10"]
+        os: [ubuntu-latest]
+        environment: ["integration"]
+    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 }}
+    defaults:
+      run:
+        working-directory: python
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          # Configure a constant location for the uv cache
+          UV_CACHE_DIR: /tmp/.uv-cache
+      - 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
+        timeout-minutes: 10
+        run: uv run poe azure-ai-tests -n logical --dist loadfile --dist worksteal --timeout 300 --retries 3 --retry-delay 10
+        working-directory: ./python
+      - name: Test Azure AI samples
+        timeout-minutes: 10
+        if: env.RUN_SAMPLES_TESTS == 'true'
+        run: uv run pytest tests/samples/ -m "azure-ai"
         working-directory: ./python
       - name: Surface failing tests
         if: always()
@@ -161,7 +170,7 @@ jobs:
     runs-on: ubuntu-latest
     needs:
       [
-        python-tests-main,
+        python-tests-core,
         python-tests-azure-ai
       ]
     steps:

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

@@ -21,7 +21,7 @@ jobs:
     steps:
       - uses: actions/checkout@v5
       - name: Download coverage report
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v6
         with:
           github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
           run-id: ${{ github.event.workflow_run.id }}

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

@@ -38,7 +38,7 @@ jobs:
       - name: Run all tests with coverage report
         run: uv run poe all-tests-cov --cov-report=xml:python-coverage.xml -q --junitxml=pytest.xml
       - name: Upload coverage report
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           path: |
             python/python-coverage.xml

.github/workflows/python-tests.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: true
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
         # todo: add macos-latest when problems are resolved
         os: [ubuntu-latest, windows-latest]
     env:

.gitignore

@@ -203,4 +203,12 @@ agents.md
 
 # AI
 .claude/
-WARP.md
+WARP.md
+
+# Frontend
+**/frontend/node_modules/
+**/frontend/.vite/
+**/frontend/dist/
+
+# Database files
+*.db

COMMUNITY.md

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

docs/decisions/0006-userapproval.md

@@ -22,7 +22,6 @@ This document aims to provide options and capture the decision on how to model t
 See various features that would need to be supported via this type of mechanism, plus how various other frameworks support this:
 
 - Also see [dotnet issue 6492](https://github.com/dotnet/extensions/issues/6492), which discusses the need for a similar pattern in the context of MCP approvals.
-- Also see [the openai RunToolApprovalItem](https://openai.github.io/openai-agents-js/openai/agents/classes/runtoolapprovalitem/).
 - Also see [the openai human-in-the-loop guide](https://openai.github.io/openai-agents-js/guides/human-in-the-loop/#approval-requests).
 - Also see [the openai MCP guide](https://openai.github.io/openai-agents-js/guides/mcp/#optional-approval-flow).
 - Also see [MCP Approval Requests from OpenAI](https://platform.openai.com/docs/guides/tools-remote-mcp#approvals).

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

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

docs/design/python-package-setup.md

@@ -175,7 +175,7 @@ Sub-packages are comprised of two parts, the code itself and the dependencies, t
 - Subpackage naming should also follow this, so in principle a package name is `<vendor/folder>-<feature/brand>`, so `google-gemini`, `azure-purview`, `microsoft-copilotstudio`, etc. For smaller vendors, where it's less likely to have a multitude of connectors, we can skip the feature/brand part, so `mem0`, `redis`, etc.
 - For Microsoft services we will have two vendor folders, `azure` and `microsoft`, where `azure` contains all Azure services, while `microsoft` contains other Microsoft services, such as Copilot Studio Agents.
 
-This setup was discussed at length and the decision is captured in [ADR-0007](../decisions/0007-python-subpackages.md).
+This setup was discussed at length and the decision is captured in [ADR-0008](../decisions/0008-python-subpackages.md).
 
 #### Evolving the package structure
 For each of the advanced components, we have two reason why we may split them into a folder, with an `__init__.py` and optionally a `_files.py`:

dotnet/Directory.Packages.props

@@ -7,7 +7,7 @@
   </PropertyGroup>
   <PropertyGroup>
     <!-- Aspire -->
-    <AspireAppHostSdkVersion>9.5.1</AspireAppHostSdkVersion>
+    <AspireAppHostSdkVersion>9.5.2</AspireAppHostSdkVersion>
   </PropertyGroup>
   <ItemGroup>
     <!-- Aspire.* -->
@@ -17,39 +17,43 @@
     <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
     <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="9.8.0" />
     <!-- Azure.* -->
-    <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.6" />
+    <PackageVersion Include="Azure.AI.Agents.Persistent" Version="1.2.0-beta.7" />
     <PackageVersion Include="Azure.AI.OpenAI" Version="2.5.0-beta.1" />
     <PackageVersion Include="Azure.Identity" Version="1.17.0" />
     <PackageVersion Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.4.0" />
     <!-- System.* -->
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="9.0.10" />
+    <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
+    <PackageVersion Include="System.ClientModel" Version="1.7.0" />
     <PackageVersion Include="System.CodeDom" Version="9.0.10" />
     <PackageVersion Include="System.Collections.Immutable" Version="9.0.10" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
     <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="9.0.10" />
+    <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.0-rc.2.25502.107" />
+    <PackageVersion Include="System.Net.Http.Json" Version="9.0.10" />
     <PackageVersion Include="System.Net.ServerSentEvents" Version="9.0.10" />
     <PackageVersion Include="System.Text.Json" Version="9.0.10" />
     <PackageVersion Include="System.Threading.Channels" Version="9.0.10" />
     <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
-    <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="9.0.10" />
     <!-- OpenTelemetry -->
-    <PackageVersion Include="OpenTelemetry" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Api" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.12.0" />
-    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.12.0" />
+    <PackageVersion Include="OpenTelemetry" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Api" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Exporter.Console" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Exporter.InMemory" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.13.1" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.13.0" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Http" Version="1.13.0" />
     <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.12.0" />
     <!-- Microsoft.AspNetCore.* -->
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="9.0.10" />
     <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="9.0.4" />
     <!-- Microsoft.Extensions.* -->
-    <PackageVersion Include="Microsoft.Extensions.AI" Version="9.10.0" />
-    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="9.10.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI" Version="9.10.2" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="9.10.2" />
     <PackageVersion Include="Microsoft.Extensions.AI.AzureAIInference" Version="9.10.0-preview.1.25513.3" />
-    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="9.10.0-preview.1.25513.3" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="9.10.2-preview.1.25552.1" />
+    <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="9.0.10" />
     <PackageVersion Include="Microsoft.Extensions.Configuration" Version="9.0.10" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="9.0.10" />
     <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="9.0.10" />
@@ -63,27 +67,29 @@
     <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="9.0.10" />
     <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="9.0.10" />
     <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="$(AspireAppHostSdkVersion)" />
+    <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
     <!-- Vector Stores -->
     <PackageVersion Include="Microsoft.SemanticKernel" Version="1.66.0" />
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.InMemory" Version="1.66.0-preview" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Connectors.Qdrant" Version="1.66.0-preview" />
     <PackageVersion Include="Microsoft.SemanticKernel.Agents.Core" Version="1.66.0" />
     <PackageVersion Include="Microsoft.SemanticKernel.Agents.OpenAI" Version="1.66.0-preview" />
     <PackageVersion Include="Microsoft.SemanticKernel.Agents.AzureAI" Version="1.66.0-preview" />
     <!-- Agent SDKs -->
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.2.41" />
     <!-- A2A -->
-    <PackageVersion Include="A2A" Version="0.3.1-preview" />
-    <PackageVersion Include="A2A.AspNetCore" Version="0.3.1-preview" />
+    <PackageVersion Include="A2A" Version="0.3.3-preview" />
+    <PackageVersion Include="A2A.AspNetCore" Version="0.3.3-preview" />
     <!-- MCP -->
-    <PackageVersion Include="ModelContextProtocol" Version="0.4.0-preview.2" />
+    <PackageVersion Include="ModelContextProtocol" Version="0.4.0-preview.3" />
     <!-- Inference SDKs -->
-    <PackageVersion Include="Anthropic.SDK" Version="5.6.0" />
-    <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.4" />
-    <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.9.2" />
-    <PackageVersion Include="OllamaSharp" Version="5.4.7" />
-    <PackageVersion Include="OpenAI" Version="2.5.0" />
+    <PackageVersion Include="Anthropic.SDK" Version="5.8.0" />
+    <PackageVersion Include="AWSSDK.Extensions.Bedrock.MEAI" Version="4.0.4.1" />
+    <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.10.0" />
+    <PackageVersion Include="OllamaSharp" Version="5.4.8" />
+    <PackageVersion Include="OpenAI" Version="2.6.0" />
     <!-- Identity -->
-    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.77.1" />
+    <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.78.0" />
     <!-- Workflows -->
     <PackageVersion Include="Microsoft.Bot.ObjectModel" Version="1.2025.1003.2" />
     <PackageVersion Include="Microsoft.Bot.ObjectModel.Json" Version="1.2025.1003.2" />
@@ -92,7 +98,8 @@
     <!-- Community -->
     <PackageVersion Include="System.Linq.Async" Version="6.0.3" />
     <!-- Test -->
-    <PackageVersion Include="FluentAssertions" Version="8.7.1" />
+    <PackageVersion Include="FluentAssertions" Version="8.8.0" />
+    <PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="9.0.10" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.0.0" />
     <PackageVersion Include="Moq" Version="[4.18.4]" />
     <PackageVersion Include="Microsoft.SemanticKernel.Agents.Abstractions" Version="1.66.0" />

dotnet/agent-framework-dotnet.slnx

@@ -18,6 +18,10 @@
     <Project Path="samples/AgentWebChat/AgentWebChat.ServiceDefaults/AgentWebChat.ServiceDefaults.csproj" />
     <Project Path="samples/AgentWebChat/AgentWebChat.Web/AgentWebChat.Web.csproj" />
   </Folder>
+  <Folder Name="/Samples/AGUIClientServer/">
+    <Project Path="samples/AGUIClientServer/AGUIClient/AGUIClient.csproj" />
+    <Project Path="samples/AGUIClientServer/AGUIServer/AGUIServer.csproj" />
+  </Folder>
   <Folder Name="/Samples/GettingStarted/">
     <File Path="samples/GettingStarted/README.md" />
   </Folder>
@@ -57,16 +61,31 @@
     <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_TextSearchRag/Agent_Step18_TextSearchRag.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step19_Mem0Provider/Agent_Step19_Mem0Provider.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step20_BackgroundResponsesWithToolsAndPersistence/Agent_Step20_BackgroundResponsesWithToolsAndPersistence.csproj" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/DevUI/">
+    <File Path="samples/GettingStarted/DevUI/README.md" />
+    <Project Path="samples/GettingStarted/DevUI/DevUI_Step01_BasicUsage/DevUI_Step01_BasicUsage.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/AgentWithOpenAI/">
     <File Path="samples/GettingStarted/AgentWithOpenAI/README.md" />
     <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step01_Running/Agent_OpenAI_Step01_Running.csproj" />
     <Project Path="samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Agent_OpenAI_Step02_Reasoning.csproj" />
   </Folder>
+  <Folder Name="/Samples/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_ExternalDataSourceRAG/AgentWithRAG_Step02_ExternalDataSourceRAG.csproj" />
+  </Folder>
   <Folder Name="/Samples/GettingStarted/ModelContextProtocol/">
+    <File Path="samples/GettingStarted/ModelContextProtocol/README.md" />
     <Project Path="samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server/Agent_MCP_Server.csproj" />
     <Project Path="samples/GettingStarted/ModelContextProtocol/Agent_MCP_Server_Auth/Agent_MCP_Server_Auth.csproj" />
     <Project Path="samples/GettingStarted/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj" />
+    <Project Path="samples/GettingStarted/ModelContextProtocol/ResponseAgent_Hosted_MCP/ResponseAgent_Hosted_MCP.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/Observability/">
     <Project Path="samples/GettingStarted/AgentOpenTelemetry/AgentOpenTelemetry.csproj" />
@@ -119,6 +138,7 @@
   <Folder Name="/Samples/GettingStarted/Workflows/Observability/">
     <Project Path="samples/GettingStarted/Workflows/Observability/ApplicationInsights/ApplicationInsights.csproj" />
     <Project Path="samples/GettingStarted/Workflows/Observability/AspireDashboard/AspireDashboard.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/Observability/WorkflowAsAnAgent/WorkflowAsAnAgentObservability.csproj" />
   </Folder>
   <Folder Name="/Samples/GettingStarted/Workflows/Visualization/">
     <Project Path="samples/GettingStarted/Workflows/Visualization/Visualization.csproj" Id="99bf0bc6-2440-428e-b3e7-d880e4b7a5fd" />
@@ -130,9 +150,13 @@
     <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/SemanticKernelMigration/">
-    <File Path="samples/SemanticKernelMigration/README.md" />
+  <Folder Name="/Samples/Catalog/">
+    <Project Path="samples/Catalog/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
+    <Project Path="samples/Catalog/AgentsInWorkflows/AgentsInWorkflows.csproj" />
+    <Project Path="samples/Catalog/DeepResearchAgent/DeepResearchAgent.csproj" />
   </Folder>
   <Folder Name="/Solution Items/">
     <File Path=".editorconfig" />
@@ -160,8 +184,14 @@
   <Folder Name="/Solution Items/docs/" />
   <Folder Name="/Solution Items/docs/decisions/">
     <File Path="../docs/decisions/0001-agent-run-response.md" />
-    <File Path="../docs/decisions/0001-agent-tools.md" />
-    <File Path="../docs/decisions/0002-agent-opentelemetry-instrumentation.md" />
+    <File Path="../docs/decisions/0002-agent-tools.md" />
+    <File Path="../docs/decisions/0003-agent-opentelemetry-instrumentation.md" />
+    <File Path="../docs/decisions/0004-foundry-sdk-extensions.md" />
+    <File Path="../docs/decisions/0005-python-naming-conventions.md" />
+    <File Path="../docs/decisions/0006-userapproval.md" />
+    <File Path="../docs/decisions/0007-agent-filtering-middleware.md" />
+    <File Path="../docs/decisions/0008-python-subpackages.md" />
+    <File Path="../docs/decisions/0009-support-long-running-operations.md" />
     <File Path="../docs/decisions/adr-short-template.md" />
     <File Path="../docs/decisions/adr-template.md" />
     <File Path="../docs/decisions/README.md" />
@@ -228,6 +258,7 @@
   </Folder>
   <Folder Name="/Solution Items/src/Shared/IntegrationTests/">
     <File Path="src/Shared/IntegrationTests/AzureAIConfiguration.cs" />
+    <File Path="src/Shared/IntegrationTests/Mem0Configuration.cs" />
     <File Path="src/Shared/IntegrationTests/OpenAIConfiguration.cs" />
     <File Path="src/Shared/IntegrationTests/README.md" />
   </Folder>
@@ -249,12 +280,16 @@
   <Folder Name="/src/">
     <Project Path="src/Microsoft.Agents.AI.A2A/Microsoft.Agents.AI.A2A.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Abstractions/Microsoft.Agents.AI.Abstractions.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.AzureAI/Microsoft.Agents.AI.AzureAI.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.AGUI/Microsoft.Agents.AI.AGUI.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.AzureAI.Persistent/Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <Project Path="src/Microsoft.Agents.AI.CopilotStudio/Microsoft.Agents.AI.CopilotStudio.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.DevUI/Microsoft.Agents.AI.DevUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.OpenAI/Microsoft.Agents.AI.Hosting.OpenAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting/Microsoft.Agents.AI.Hosting.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Mem0/Microsoft.Agents.AI.Mem0.csproj" />
     <Project Path="src/Microsoft.Agents.AI.OpenAI/Microsoft.Agents.AI.OpenAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows/Microsoft.Agents.AI.Workflows.csproj" />
@@ -265,6 +300,8 @@
     <Project Path="tests/AgentConformance.IntegrationTests/AgentConformance.IntegrationTests.csproj" />
     <Project Path="tests/AzureAIAgentsPersistent.IntegrationTests/AzureAIAgentsPersistent.IntegrationTests.csproj" />
     <Project Path="tests/CopilotStudio.IntegrationTests/CopilotStudio.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Mem0.IntegrationTests/Microsoft.Agents.AI.Mem0.IntegrationTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests.csproj" />
     <Project Path="tests/OpenAIAssistant.IntegrationTests/OpenAIAssistant.IntegrationTests.csproj" />
     <Project Path="tests/OpenAIChatCompletion.IntegrationTests/OpenAIChatCompletion.IntegrationTests.csproj" />
@@ -272,13 +309,17 @@
   </Folder>
   <Folder Name="/Tests/UnitTests/">
     <Project Path="tests/Microsoft.Agents.AI.A2A.UnitTests/Microsoft.Agents.AI.A2A.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.AGUI.UnitTests/Microsoft.Agents.AI.AGUI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Abstractions.UnitTests/Microsoft.Agents.AI.Abstractions.UnitTests.csproj" />
-    <Project Path="tests/Microsoft.Agents.AI.AzureAI.UnitTests/Microsoft.Agents.AI.AzureAI.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests/Microsoft.Agents.AI.AzureAI.Persistent.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.A2A.Tests/Microsoft.Agents.AI.Hosting.A2A.Tests.csproj" Id="2a1c544d-237d-4436-8732-ba0c447ac06b" />
+    <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.OpenAI.UnitTests/Microsoft.Agents.AI.Hosting.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Hosting.UnitTests/Microsoft.Agents.AI.Hosting.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Mem0.UnitTests/Microsoft.Agents.AI.Mem0.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.OpenAI.UnitTests/Microsoft.Agents.AI.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.UnitTests/Microsoft.Agents.AI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.UnitTests/Microsoft.Agents.AI.Workflows.UnitTests.csproj" />
   </Folder>
-</Solution>
+</Solution>

dotnet/nuget/nuget-package.props

@@ -2,9 +2,9 @@
   <PropertyGroup>
     <!-- Central version prefix - applies to all nuget packages. -->
     <VersionPrefix>1.0.0</VersionPrefix>
-    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).251016.1</PackageVersion>
-    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.251016.1</PackageVersion>
-    <GitTag>1.0.0-preview.251016.1</GitTag>
+    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).251105.1</PackageVersion>
+    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.251105.1</PackageVersion>
+    <GitTag>1.0.0-preview.251105.1</GitTag>
 
     <Configurations>Debug;Release;Publish</Configurations>
     <IsPackable>true</IsPackable>

dotnet/samples/A2AClientServer/A2AServer/A2AServer.csproj

@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
@@ -9,7 +9,6 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="A2A.AspNetCore" />
     <PackageReference Include="Azure.AI.Agents.Persistent" />
     <PackageReference Include="Azure.Identity" />
     <PackageReference Include="Microsoft.Bcl.AsyncInterfaces" VersionOverride="10.0.0-rc.2.25502.107" />
@@ -17,8 +16,11 @@
   </ItemGroup>
 
   <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting.A2A.AspNetCore\Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting.A2A\Microsoft.Agents.AI.Hosting.A2A.csproj" />
+
     <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.A2A\Microsoft.Agents.AI.A2A.csproj" />
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
   </ItemGroup>
 

dotnet/samples/A2AClientServer/A2AServer/HostAgentFactory.cs

@@ -4,7 +4,6 @@ using A2A;
 using Azure.AI.Agents.Persistent;
 using Azure.Identity;
 using Microsoft.Agents.AI;
-using Microsoft.Agents.AI.A2A;
 using Microsoft.Extensions.AI;
 using OpenAI;
 
@@ -12,7 +11,7 @@ namespace A2AServer;
 
 internal static class HostAgentFactory
 {
-    internal static async Task<A2AHostAgent> CreateFoundryHostAgentAsync(string agentType, string model, string endpoint, string assistantId, IList<AITool>? tools = null)
+    internal static async Task<(AIAgent, AgentCard)> CreateFoundryHostAgentAsync(string agentType, string model, string endpoint, string assistantId, IList<AITool>? tools = null)
     {
         var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
         PersistentAgent persistentAgent = await persistentAgentsClient.Administration.GetAgentAsync(assistantId);
@@ -28,10 +27,10 @@ internal static class HostAgentFactory
             _ => throw new ArgumentException($"Unsupported agent type: {agentType}"),
         };
 
-        return new A2AHostAgent(agent, agentCard);
+        return new(agent, agentCard);
     }
 
-    internal static async Task<A2AHostAgent> CreateChatCompletionHostAgentAsync(string agentType, string model, string apiKey, string name, string instructions, IList<AITool>? tools = null)
+    internal static async Task<(AIAgent, AgentCard)> CreateChatCompletionHostAgentAsync(string agentType, string model, string apiKey, string name, string instructions, IList<AITool>? tools = null)
     {
         AIAgent agent = new OpenAIClient(apiKey)
              .GetChatClient(model)
@@ -45,7 +44,7 @@ internal static class HostAgentFactory
             _ => throw new ArgumentException($"Unsupported agent type: {agentType}"),
         };
 
-        return new A2AHostAgent(agent, agentCard);
+        return new(agent, agentCard);
     }
 
     #region private

dotnet/samples/A2AClientServer/A2AServer/Program.cs

@@ -2,7 +2,7 @@
 using A2A;
 using A2A.AspNetCore;
 using A2AServer;
-using Microsoft.Agents.AI.A2A;
+using Microsoft.Agents.AI;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.Configuration;
@@ -47,10 +47,12 @@ IList<AITool> tools =
     AIFunctionFactory.Create(invoiceQueryPlugin.QueryByInvoiceId)
     ];
 
-A2AHostAgent? hostAgent = null;
+AIAgent hostA2AAgent;
+AgentCard hostA2AAgentCard;
+
 if (!string.IsNullOrEmpty(endpoint) && !string.IsNullOrEmpty(agentId))
 {
-    hostAgent = agentType.ToUpperInvariant() switch
+    (hostA2AAgent, hostA2AAgentCard) = agentType.ToUpperInvariant() switch
     {
         "INVOICE" => await HostAgentFactory.CreateFoundryHostAgentAsync(agentType, model, endpoint, agentId, tools),
         "POLICY" => await HostAgentFactory.CreateFoundryHostAgentAsync(agentType, model, endpoint, agentId),
@@ -60,7 +62,7 @@ if (!string.IsNullOrEmpty(endpoint) && !string.IsNullOrEmpty(agentId))
 }
 else if (!string.IsNullOrEmpty(apiKey))
 {
-    hostAgent = agentType.ToUpperInvariant() switch
+    (hostA2AAgent, hostA2AAgentCard) = agentType.ToUpperInvariant() switch
     {
         "INVOICE" => await HostAgentFactory.CreateChatCompletionHostAgentAsync(
             agentType, model, apiKey, "InvoiceAgent",
@@ -102,7 +104,10 @@ else
     throw new ArgumentException("Either A2AServer:ApiKey or A2AServer:ConnectionString & agentId must be provided");
 }
 
-app.MapA2A(hostAgent!.TaskManager!, "/");
-app.MapWellKnownAgentCard(hostAgent!.TaskManager!, "/");
+var a2aTaskManager = app.MapA2A(
+    hostA2AAgent,
+    path: "/",
+    agentCard: hostA2AAgentCard,
+    taskManager => app.MapWellKnownAgentCard(taskManager, "/"));
 
 await app.RunAsync();

dotnet/samples/AGUIClientServer/AGUIClient/AGUIClient.csproj

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

dotnet/samples/AGUIClientServer/AGUIClient/Program.cs

@@ -0,0 +1,137 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use the AG-UI client to connect to a remote AG-UI server
+// and display streaming updates including conversation/response metadata, text content, and errors.
+
+using System.CommandLine;
+using System.Reflection;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.AGUI;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Logging;
+
+namespace AGUIClient;
+
+public static class Program
+{
+    public static async Task<int> Main(string[] args)
+    {
+        // Create root command with options
+        RootCommand rootCommand = new("AGUIClient");
+        rootCommand.SetAction((_, ct) => HandleCommandsAsync(ct));
+
+        // Run the command
+        return await rootCommand.Parse(args).InvokeAsync();
+    }
+
+    private static async Task HandleCommandsAsync(CancellationToken cancellationToken)
+    {
+        // Set up the logging
+        using ILoggerFactory loggerFactory = LoggerFactory.Create(builder =>
+        {
+            builder.AddConsole();
+            builder.SetMinimumLevel(LogLevel.Information);
+        });
+        ILogger logger = loggerFactory.CreateLogger("AGUIClient");
+
+        // Retrieve configuration settings
+        IConfigurationRoot configRoot = new ConfigurationBuilder()
+            .AddEnvironmentVariables()
+            .AddUserSecrets(Assembly.GetExecutingAssembly())
+            .Build();
+
+        string serverUrl = configRoot["AGUI_SERVER_URL"] ?? "http://localhost:5100";
+
+        logger.LogInformation("Connecting to AG-UI server at: {ServerUrl}", serverUrl);
+
+        // Create the AG-UI client agent
+        using HttpClient httpClient = new()
+        {
+            Timeout = TimeSpan.FromSeconds(60)
+        };
+
+        AGUIAgent agent = new(
+            id: "agui-client",
+            description: "AG-UI Client Agent",
+            httpClient: httpClient,
+            endpoint: serverUrl);
+
+        AgentThread thread = agent.GetNewThread();
+        List<ChatMessage> messages = [new(ChatRole.System, "You are a helpful assistant.")];
+        try
+        {
+            while (true)
+            {
+                // Get user message
+                Console.Write("\nUser (:q or quit to exit): ");
+                string? message = Console.ReadLine();
+                if (string.IsNullOrWhiteSpace(message))
+                {
+                    Console.WriteLine("Request cannot be empty.");
+                    continue;
+                }
+
+                if (message is ":q" or "quit")
+                {
+                    break;
+                }
+
+                messages.Add(new(ChatRole.User, message));
+
+                // Call RunStreamingAsync to get streaming updates
+                bool isFirstUpdate = true;
+                string? threadId = null;
+                await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(messages, thread, cancellationToken: cancellationToken))
+                {
+                    // Use AsChatResponseUpdate to access ChatResponseUpdate properties
+                    ChatResponseUpdate chatUpdate = update.AsChatResponseUpdate();
+                    if (chatUpdate.ConversationId != null)
+                    {
+                        threadId = chatUpdate.ConversationId;
+                    }
+
+                    // Display run started information from the first update
+                    if (isFirstUpdate && threadId != null && update.ResponseId != null)
+                    {
+                        Console.ForegroundColor = ConsoleColor.Yellow;
+                        Console.WriteLine($"\n[Run Started - Thread: {threadId}, Run: {update.ResponseId}]");
+                        Console.ResetColor();
+                        isFirstUpdate = false;
+                    }
+
+                    // Display different content types with appropriate formatting
+                    foreach (AIContent content in update.Contents)
+                    {
+                        switch (content)
+                        {
+                            case TextContent textContent:
+                                Console.ForegroundColor = ConsoleColor.Cyan;
+                                Console.Write(textContent.Text);
+                                Console.ResetColor();
+                                break;
+
+                            case ErrorContent errorContent:
+                                Console.ForegroundColor = ConsoleColor.Red;
+                                string code = errorContent.AdditionalProperties?["Code"] as string ?? "Unknown";
+                                Console.WriteLine($"\n[Error - Code: {code}, Message: {errorContent.Message}]");
+                                Console.ResetColor();
+                                break;
+                        }
+                    }
+                }
+                messages.Clear();
+                Console.WriteLine();
+            }
+        }
+        catch (OperationCanceledException)
+        {
+            logger.LogInformation("AGUIClient operation was canceled.");
+        }
+        catch (Exception ex) when (ex is not OutOfMemoryException and not StackOverflowException and not ThreadAbortException and not AccessViolationException)
+        {
+            logger.LogError(ex, "An error occurred while running the AGUIClient");
+            return;
+        }
+    }
+}

dotnet/samples/AGUIClientServer/AGUIClient/README.md

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

dotnet/samples/AGUIClientServer/AGUIServer/AGUIServer.csproj

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

dotnet/samples/AGUIClientServer/AGUIServer/AGUIServer.http

@@ -0,0 +1,17 @@
+@host = http://localhost:5100
+
+### Send a message to the AG-UI agent
+POST {{host}}/
+Content-Type: application/json
+
+{
+  "threadId": "thread_123",
+  "runId": "run_456",
+  "messages": [
+    {
+      "role": "user",
+      "content": "What is the capital of France?"
+    }
+  ],
+  "context": {}
+}

dotnet/samples/AGUIClientServer/AGUIServer/Program.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
+using Microsoft.Extensions.AI;
+using OpenAI;
+
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+builder.Services.AddHttpClient().AddLogging();
+WebApplication app = builder.Build();
+
+string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
+
+// Create the AI agent
+var agent = new AzureOpenAIClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential())
+    .GetChatClient(deploymentName)
+    .CreateAIAgent(name: "AGUIAssistant");
+
+// Map the AG-UI agent endpoint
+app.MapAGUI("/", agent);
+
+await app.RunAsync();

dotnet/samples/AGUIClientServer/README.md

@@ -0,0 +1,202 @@
+# AG-UI Client and Server Sample
+
+This sample demonstrates how to use the AG-UI (Agent UI) protocol to enable communication between a client application and a remote agent server. The AG-UI protocol provides a standardized way for clients to interact with AI agents.
+
+## Overview
+
+The demonstration has two components:
+
+1. **AGUIServer** - An ASP.NET Core web server that hosts an AI agent and exposes it via the AG-UI protocol
+2. **AGUIClient** - A console application that connects to the AG-UI server and displays streaming updates
+
+> **Warning**
+> The AG-UI protocol is still under development and changing.
+> We will try to keep these samples updated as the protocol evolves.
+
+## Configuring Environment Variables
+
+Configure the required Azure OpenAI environment variables:
+
+```powershell
+$env:AZURE_OPENAI_ENDPOINT="<<your-model-endpoint>>"
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4.1-mini"
+```
+
+> **Note:** This sample uses `DefaultAzureCredential` for authentication. Make sure you're authenticated with Azure (e.g., via `az login`, Visual Studio, or environment variables).
+
+## Running the Sample
+
+### Step 1: Start the AG-UI Server
+
+```bash
+cd AGUIServer
+dotnet build
+dotnet run --urls "http://localhost:5100"
+```
+
+The server will start and listen on `http://localhost:5100`.
+
+### Step 2: Testing with the REST Client (Optional)
+
+Before running the client, you can test the server using the included `.http` file:
+
+1. Open [./AGUIServer/AGUIServer.http](./AGUIServer/AGUIServer.http) in Visual Studio or VS Code with the REST Client extension
+2. Send a test request to verify the server is working
+3. Observe the server-sent events stream in the response
+
+Sample request:
+```http
+POST http://localhost:5100/
+Content-Type: application/json
+
+{
+  "threadId": "thread_123",
+  "runId": "run_456",
+  "messages": [
+    {
+      "role": "user",
+      "content": "What is the capital of France?"
+    }
+  ],
+  "context": {}
+}
+```
+
+### Step 3: Run the AG-UI Client
+
+In a new terminal window:
+
+```bash
+cd AGUIClient
+dotnet run
+```
+
+Optionally, configure a different server URL:
+
+```powershell
+$env:AGUI_SERVER_URL="http://localhost:5100"
+```
+
+### Step 4: Interact with the Agent
+
+1. The client will connect to the AG-UI server
+2. Enter your message at the prompt
+3. Observe the streaming updates with color-coded output:
+   - **Yellow**: Run started notification showing thread and run IDs
+   - **Cyan**: Agent's text response (streamed character by character)
+   - **Green**: Run finished notification
+   - **Red**: Error messages (if any occur)
+4. Type `:q` or `quit` to exit
+
+## Sample Output
+
+```
+AGUIClient> dotnet run
+info: AGUIClient[0]
+      Connecting to AG-UI server at: http://localhost:5100
+
+User (:q or quit to exit): What is the capital of France?
+
+[Run Started - Thread: thread_abc123, Run: run_xyz789]
+The capital of France is Paris. It is known for its rich history, culture, and iconic landmarks such as the Eiffel Tower and the Louvre Museum.
+[Run Finished - Thread: thread_abc123, Run: run_xyz789]
+
+User (:q or quit to exit): Tell me a fun fact about space
+
+[Run Started - Thread: thread_abc123, Run: run_def456]
+Here's a fun fact: A day on Venus is longer than its year! Venus takes about 243 Earth days to rotate once on its axis, but only about 225 Earth days to orbit the Sun.
+[Run Finished - Thread: thread_abc123, Run: run_def456]
+
+User (:q or quit to exit): :q
+```
+
+## How It Works
+
+### Server Side
+
+The `AGUIServer` uses the `MapAGUI` extension method to expose an agent through the AG-UI protocol:
+
+```csharp
+AIAgent agent = new OpenAIClient(apiKey)
+    .GetChatClient(model)
+    .CreateAIAgent(
+        instructions: "You are a helpful assistant.",
+        name: "AGUIAssistant");
+
+app.MapAGUI("/", agent);
+```
+
+This automatically handles:
+- HTTP POST requests with message payloads
+- Converting agent responses to AG-UI event streams
+- Server-sent events (SSE) formatting
+- Thread and run management
+
+### Client Side
+
+The `AGUIClient` uses the `AGUIAgent` class to connect to the remote server:
+
+```csharp
+AGUIAgent agent = new(
+    id: "agui-client",
+    description: "AG-UI Client Agent",
+    messages: [],
+    httpClient: httpClient,
+    endpoint: serverUrl);
+
+bool isFirstUpdate = true;
+AgentRunResponseUpdate? currentUpdate = null;
+
+await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(messages, thread))
+{
+    // First update indicates run started
+    if (isFirstUpdate)
+    {
+        Console.WriteLine($"[Run Started - Thread: {update.ConversationId}, Run: {update.ResponseId}]");
+        isFirstUpdate = false;
+    }
+    
+    currentUpdate = update;
+    
+    foreach (AIContent content in update.Contents)
+    {
+        switch (content)
+        {
+            case TextContent textContent:
+                // Display streaming text
+                Console.Write(textContent.Text);
+                break;
+            case ErrorContent errorContent:
+                // Display error notification
+                Console.WriteLine($"[Error: {errorContent.Message}]");
+                break;
+        }
+    }
+}
+
+// Last update indicates run finished
+if (currentUpdate != null)
+{
+    Console.WriteLine($"\n[Run Finished - Thread: {currentUpdate.ConversationId}, Run: {currentUpdate.ResponseId}]");
+}
+```
+
+The `RunStreamingAsync` method:
+1. Sends messages to the server via HTTP POST
+2. Receives server-sent events (SSE) stream
+3. Parses events into `AgentRunResponseUpdate` objects
+4. Yields updates as they arrive for real-time display
+
+## Key Concepts
+
+- **Thread**: Represents a conversation context that persists across multiple runs (accessed via `ConversationId` property)
+- **Run**: A single execution of the agent for a given set of messages (identified by `ResponseId` property)
+- **AgentRunResponseUpdate**: Contains the response data with:
+  - `ResponseId`: The unique run identifier
+  - `ConversationId`: The thread/conversation identifier
+  - `Contents`: Collection of content items (TextContent, ErrorContent, etc.)
+- **Run Lifecycle**: 
+  - The **first** `AgentRunResponseUpdate` in a run indicates the run has started
+  - Subsequent updates contain streaming content as the agent processes
+  - The **last** `AgentRunResponseUpdate` in a run indicates the run has finished
+  - If an error occurs, the update will contain `ErrorContent`

dotnet/samples/AgentWebChat/AgentWebChat.AgentHost/Program.cs

@@ -5,8 +5,6 @@ using AgentWebChat.AgentHost;
 using AgentWebChat.AgentHost.Utilities;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Hosting;
-using Microsoft.Agents.AI.Hosting.A2A.AspNetCore;
-using Microsoft.Agents.AI.Hosting.OpenAI;
 using Microsoft.Agents.AI.Workflows;
 using Microsoft.Extensions.AI;
 
@@ -22,13 +20,14 @@ builder.Services.AddProblemDetails();
 // Configure the chat model and our agent.
 builder.AddKeyedChatClient("chat-model");
 
-builder.AddAIAgent(
+var pirateAgentBuilder = builder.AddAIAgent(
     "pirate",
     instructions: "You are a pirate. Speak like a pirate",
     description: "An agent that speaks like a pirate.",
-    chatClientServiceKey: "chat-model");
+    chatClientServiceKey: "chat-model")
+    .WithInMemoryThreadStore();
 
-builder.AddAIAgent("knights-and-knaves", (sp, key) =>
+var knightsKnavesAgentBuilder = builder.AddAIAgent("knights-and-knaves", (sp, key) =>
 {
     var chatClient = sp.GetRequiredKeyedService<IChatClient>("chat-model");
 
@@ -60,10 +59,7 @@ builder.AddAIAgent("knights-and-knaves", (sp, key) =>
         If the user asks a general question about their surrounding, make something up which is consistent with the scenario.
         """, "Narrator");
 
-    // TODO: How to avoid sync-over-async here?
-#pragma warning disable VSTHRD002 // Avoid problematic synchronous waits
-    return AgentWorkflowBuilder.BuildConcurrent([knight, knave, narrator]).AsAgentAsync(name: key).AsTask().GetAwaiter().GetResult();
-#pragma warning restore VSTHRD002
+    return AgentWorkflowBuilder.BuildConcurrent([knight, knave, narrator]).AsAgent(name: key);
 });
 
 // Workflow consisting of multiple specialized agents
@@ -85,6 +81,9 @@ var literatureAgent = builder.AddAIAgent("literator",
 builder.AddSequentialWorkflow("science-sequential-workflow", [chemistryAgent, mathsAgent, literatureAgent]).AddAsAIAgent();
 builder.AddConcurrentWorkflow("science-concurrent-workflow", [chemistryAgent, mathsAgent, literatureAgent]).AddAsAIAgent();
 
+builder.AddOpenAIChatCompletions();
+builder.AddOpenAIResponses();
+
 var app = builder.Build();
 
 app.MapOpenApi();
@@ -105,15 +104,10 @@ app.MapA2A(agentName: "knights-and-knaves", path: "/a2a/knights-and-knaves", age
     // Url = "http://localhost:5390/a2a/knights-and-knaves"
 });
 
-app.MapOpenAIResponses("pirate");
-app.MapOpenAIResponses("knights-and-knaves");
+app.MapOpenAIResponses();
 
-app.MapOpenAIChatCompletions("pirate");
-app.MapOpenAIChatCompletions("knights-and-knaves");
-
-// workflow-agents
-app.MapOpenAIResponses("science-sequential-workflow");
-app.MapOpenAIResponses("science-concurrent-workflow");
+app.MapOpenAIChatCompletions(pirateAgentBuilder);
+app.MapOpenAIChatCompletions(knightsKnavesAgentBuilder);
 
 // Map the agents HTTP endpoints
 app.MapAgentDiscovery("/agents");

dotnet/samples/AgentWebChat/AgentWebChat.Web/A2AAgentClient.cs

@@ -58,7 +58,7 @@ internal sealed class A2AAgentClient : AgentClientBase
             if (a2aResponse is AgentMessage message)
             {
                 var responseMessage = message.ToChatMessage();
-                if (responseMessage is not null)
+                if (responseMessage is { Contents.Count: > 0 })
                 {
                     results.Add(new AgentRunResponseUpdate(responseMessage.Role, responseMessage.Contents)
                     {
@@ -78,11 +78,7 @@ internal sealed class A2AAgentClient : AgentClientBase
 
                         foreach (var part in artifact.Parts)
                         {
-                            var aiContent = ConvertPartToAIContent(part);
-                            if (aiContent != null)
-                            {
-                                (aiContents ??= []).Add(aiContent);
-                            }
+                            (aiContents ??= []).Add(part.ToAIContent());
                         }
 
                         if (aiContents is not null)
@@ -155,20 +151,6 @@ internal sealed class A2AAgentClient : AgentClientBase
             return (a2aClient, a2aCardResolver);
         });
 
-    private static AIContent? ConvertPartToAIContent(Part part) =>
-        part switch
-        {
-            TextPart textPart => new TextContent(textPart.Text)
-            {
-                RawRepresentation = textPart
-            },
-            FilePart filePart when filePart.File is FileWithUri fileWithUrl => new HostedFileContent(fileWithUrl.Uri)
-            {
-                RawRepresentation = filePart
-            },
-            _ => null
-        };
-
     private static AdditionalPropertiesDictionary? ConvertMetadataToAdditionalProperties(Dictionary<string, JsonElement>? metadata)
     {
         if (metadata is not { Count: > 0 })
@@ -184,22 +166,3 @@ internal sealed class A2AAgentClient : AgentClientBase
         return additionalProperties;
     }
 }
-
-// Extension method to convert multiple chat messages to A2A messages
-internal static class ChatMessageExtensions
-{
-    public static List<AgentMessage> ToA2AMessages(this IList<ChatMessage> chatMessages)
-    {
-        if (chatMessages is null || chatMessages.Count == 0)
-        {
-            return [];
-        }
-
-        var result = new List<AgentMessage>();
-        foreach (var chatMessage in chatMessages)
-        {
-            result.Add(chatMessage.ToA2AMessage());
-        }
-        return result;
-    }
-}

dotnet/samples/AgentWebChat/AgentWebChat.Web/OpenAIResponsesAgentClient.cs

@@ -23,11 +23,11 @@ internal sealed class OpenAIResponsesAgentClient(HttpClient httpClient) : AgentC
     {
         OpenAIClientOptions options = new()
         {
-            Endpoint = new Uri(httpClient.BaseAddress!, $"/{agentName}/v1/"),
+            Endpoint = new Uri(httpClient.BaseAddress!, "/v1/"),
             Transport = new HttpClientPipelineTransport(httpClient)
         };
 
-        var openAiClient = new OpenAIResponseClient(model: "myModel!", credential: new ApiKeyCredential("dummy-key"), options: options).AsIChatClient();
+        var openAiClient = new OpenAIResponseClient(model: agentName, credential: new ApiKeyCredential("dummy-key"), options: options).AsIChatClient();
         var chatOptions = new ChatOptions()
         {
             ConversationId = threadId

dotnet/samples/Catalog/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/Catalog/AgentWithTextSearchRag/Program.cs

@@ -0,0 +1,82 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use TextSearchProvider to add retrieval augmented generation (RAG)
+// capabilities to an AI agent. The provider runs a search against an external knowledge base
+// before each model invocation and injects the results into the model context.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Data;
+using Microsoft.Extensions.AI;
+using OpenAI;
+
+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";
+
+TextSearchProviderOptions textSearchOptions = new()
+{
+    // Run the search prior to every model invocation and keep a short rolling window of conversation context.
+    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
+    RecentMessageMemoryLimit = 6,
+};
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new AzureCliCredential())
+    .GetChatClient(deploymentName)
+    .CreateAIAgent(new ChatClientAgentOptions
+    {
+        Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available.",
+        AIContextProviderFactory = ctx => new TextSearchProvider(MockSearchAsync, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)
+    });
+
+AgentThread thread = agent.GetNewThread();
+
+Console.WriteLine(">> Asking about returns\n");
+Console.WriteLine(await agent.RunAsync("Hi! I need help understanding the return policy.", thread));
+
+Console.WriteLine("\n>> Asking about shipping\n");
+Console.WriteLine(await agent.RunAsync("How long does standard shipping usually take?", thread));
+
+Console.WriteLine("\n>> Asking about product care\n");
+Console.WriteLine(await agent.RunAsync("What is the best way to maintain the TrailRunner tent fabric?", thread));
+
+static Task<IEnumerable<TextSearchProvider.TextSearchResult>> MockSearchAsync(string query, CancellationToken cancellationToken)
+{
+    // The mock search inspects the user's question and returns pre-defined snippets
+    // that resemble documents stored in an external knowledge source.
+    List<TextSearchProvider.TextSearchResult> results = new();
+
+    if (query.Contains("return", StringComparison.OrdinalIgnoreCase) || query.Contains("refund", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "Contoso Outdoors Return Policy",
+            SourceLink = "https://contoso.com/policies/returns",
+            Text = "Customers may return any item within 30 days of delivery. Items should be unused and include original packaging. Refunds are issued to the original payment method within 5 business days of inspection."
+        });
+    }
+
+    if (query.Contains("shipping", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "Contoso Outdoors Shipping Guide",
+            SourceLink = "https://contoso.com/help/shipping",
+            Text = "Standard shipping is free on orders over $50 and typically arrives in 3-5 business days within the continental United States. Expedited options are available at checkout."
+        });
+    }
+
+    if (query.Contains("tent", StringComparison.OrdinalIgnoreCase) || query.Contains("fabric", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "TrailRunner Tent Care Instructions",
+            SourceLink = "https://contoso.com/manuals/trailrunner-tent",
+            Text = "Clean the tent fabric with lukewarm water and a non-detergent soap. Allow it to air dry completely before storage and avoid prolonged UV exposure to extend the lifespan of the waterproof coating."
+        });
+    }
+
+    return Task.FromResult<IEnumerable<TextSearchProvider.TextSearchResult>>(results);
+}

dotnet/samples/Catalog/AgentWithTextSearchRag/README.md

@@ -0,0 +1,41 @@
+# What this sample demonstrates
+
+This sample demonstrates how to use TextSearchProvider to add retrieval augmented generation (RAG) capabilities to an AI agent. The provider runs a search against an external knowledge base before each model invocation and injects the results into the model context.
+
+Key features:
+- Configuring TextSearchProvider with custom search behavior
+- Running searches before AI invocations to provide relevant context
+- Managing conversation memory with a rolling window approach
+- Citing source documents in AI responses
+
+## Prerequisites
+
+Before running this sample, ensure you have:
+
+1. An Azure OpenAI endpoint configured
+2. A deployment of a chat model (e.g., gpt-4o-mini)
+3. Azure CLI installed and authenticated
+
+## Environment Variables
+
+Set the following environment variables:
+
+```powershell
+# Replace with your Azure OpenAI endpoint
+$env:AZURE_OPENAI_ENDPOINT="https://your-openai-resource.openai.azure.com/"
+
+# Optional, defaults to gpt-4o-mini
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"
+```
+
+## How It Works
+
+The sample uses a mock search function that demonstrates the RAG pattern:
+
+1. When the user asks a question, the TextSearchProvider intercepts it
+2. The search function looks for relevant documents based on the query
+3. Retrieved documents are injected into the model's context
+4. The AI responds using both its training and the provided context
+5. The agent can cite specific source documents in its answers
+
+The mock search function returns pre-defined snippets for demonstration purposes. In a production scenario, you would replace this with actual searches against your knowledge base (e.g., Azure AI Search, vector database, etc.).

dotnet/samples/Catalog/AgentsInWorkflows/AgentsInWorkflows.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/Catalog/AgentsInWorkflows/Program.cs

@@ -0,0 +1,48 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to integrate AI agents into a workflow pipeline.
+// Three translation agents are connected sequentially to create a translation chain:
+// English → French → Spanish → English, showing how agents can be composed as workflow executors.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+// Set up the Azure OpenAI client
+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";
+
+IChatClient chatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+    .GetChatClient(deploymentName)
+    .AsIChatClient();
+
+// Create agents
+AIAgent frenchAgent = GetTranslationAgent("French", chatClient);
+AIAgent spanishAgent = GetTranslationAgent("Spanish", chatClient);
+AIAgent englishAgent = GetTranslationAgent("English", chatClient);
+
+// Build the workflow by adding executors and connecting them
+Workflow workflow = new WorkflowBuilder(frenchAgent)
+    .AddEdge(frenchAgent, spanishAgent)
+    .AddEdge(spanishAgent, englishAgent)
+.Build();
+
+// Execute the workflow
+await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, new ChatMessage(ChatRole.User, "Hello World!"));
+
+// Must send the turn token to trigger the agents.
+// The agents are wrapped as executors. When they receive messages,
+// they will cache the messages and only start processing when they receive a TurnToken.
+await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+{
+    if (evt is AgentRunUpdateEvent executorComplete)
+    {
+        Console.WriteLine($"{executorComplete.ExecutorId}: {executorComplete.Data}");
+    }
+}
+
+static ChatClientAgent GetTranslationAgent(string targetLanguage, IChatClient chatClient) =>
+    new(chatClient, $"You are a translation assistant that translates the provided text to {targetLanguage}.");

dotnet/samples/Catalog/AgentsInWorkflows/README.md

@@ -0,0 +1,26 @@
+# What this sample demonstrates
+
+This sample demonstrates the use of AI agents as executors within a workflow.
+
+This workflow uses three translation agents:
+1. French Agent - translates input text to French
+2. Spanish Agent - translates French text to Spanish
+3. English Agent - translates Spanish text back to English
+
+The agents are connected sequentially, creating a translation chain that demonstrates how AI-powered components can be seamlessly integrated into workflow pipelines.
+
+## Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 8.0 SDK or later
+- Azure OpenAI 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 OpenAI 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_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

dotnet/samples/Catalog/DeepResearchAgent/DeepResearchAgent.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Agents.Persistent" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/Catalog/DeepResearchAgent/Program.cs

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to create an Azure AI Foundry Agent with the Deep Research Tool.
+
+using Azure.AI.Agents.Persistent;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
+var deepResearchDeploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEEP_RESEARCH_DEPLOYMENT_NAME") ?? "o3-deep-research";
+var modelDeploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o";
+var bingConnectionId = Environment.GetEnvironmentVariable("BING_CONNECTION_ID") ?? throw new InvalidOperationException("BING_CONNECTION_ID is not set.");
+
+// Configure extended network timeout for long-running Deep Research tasks.
+PersistentAgentsAdministrationClientOptions persistentAgentsClientOptions = new();
+persistentAgentsClientOptions.Retry.NetworkTimeout = TimeSpan.FromMinutes(20);
+
+// Get a client to create/retrieve server side agents with.
+PersistentAgentsClient persistentAgentsClient = new(endpoint, new AzureCliCredential(), persistentAgentsClientOptions);
+
+// Define and configure the Deep Research tool.
+DeepResearchToolDefinition deepResearchTool = new(new DeepResearchDetails(
+    bingGroundingConnections: [new(bingConnectionId)],
+    model: deepResearchDeploymentName)
+ );
+
+// Create an agent with the Deep Research tool on the Azure AI agent service.
+AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
+    model: modelDeploymentName,
+    name: "DeepResearchAgent",
+    instructions: "You are a helpful Agent that assists in researching scientific topics.",
+    tools: [deepResearchTool]);
+
+const string Task = "Research the current state of studies on orca intelligence and orca language, " +
+    "including what is currently known about orcas' cognitive capabilities and communication systems.";
+
+Console.WriteLine($"# User: '{Task}'");
+Console.WriteLine();
+
+try
+{
+    AgentThread thread = agent.GetNewThread();
+
+    await foreach (var response in agent.RunStreamingAsync(Task, thread))
+    {
+        Console.Write(response.Text);
+    }
+}
+finally
+{
+    await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
+}

dotnet/samples/Catalog/DeepResearchAgent/README.md

@@ -0,0 +1,47 @@
+# What this sample demonstrates
+
+This sample demonstrates how to create an Azure AI Agent with the Deep Research Tool, which leverages the o3-deep-research reasoning model to perform comprehensive research on complex topics.
+
+Key features:
+- Configuring and using the Deep Research Tool with Bing grounding
+- Creating a persistent AI agent with deep research capabilities
+- Executing deep research queries and retrieving results
+
+## Prerequisites
+
+Before running this sample, ensure you have:
+
+1. An Azure AI Foundry project set up
+2. A deep research model deployment (e.g., o3-deep-research)
+3. A model deployment (e.g., gpt-4o)
+4. A Bing Connection configured in your Azure AI Foundry project
+5. Azure CLI installed and authenticated
+
+**Important**: Please visit the following documentation for detailed setup instructions:
+- [Deep Research Tool Documentation](https://aka.ms/agents-deep-research)
+- [Research Tool Setup](https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/tools/deep-research#research-tool-setup)
+
+Pay special attention to the purple `Note` boxes in the Azure documentation.
+
+**Note**: The Bing Connection ID must be from the **project**, not the resource. It has the following format:
+
+```
+/subscriptions/<sub_id>/resourceGroups/<rg_name>/providers/<provider_name>/accounts/<account_name>/projects/<project_name>/connections/<connection_name>
+```
+
+## Environment Variables
+
+Set the following environment variables:
+
+```powershell
+# Replace with your Azure AI Foundry project endpoint
+$env:AZURE_FOUNDRY_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/"
+
+# Replace with your Bing connection ID from the project
+$env:BING_CONNECTION_ID="/subscriptions/.../connections/your-bing-connection"
+
+# Optional, defaults to o3-deep-research
+$env:AZURE_FOUNDRY_PROJECT_DEEP_RESEARCH_DEPLOYMENT_NAME="o3-deep-research"
+
+# Optional, defaults to gpt-4o
+$env:AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME="gpt-4o"

dotnet/samples/GettingStarted/A2A/A2AAgent_AsFunctionTools/Program.cs

@@ -23,7 +23,7 @@ A2ACardResolver agentCardResolver = new(new Uri(a2aAgentHost));
 AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
 
 // Create an instance of the AIAgent for an existing A2A agent specified by the agent card.
-AIAgent a2aAgent = await agentCard.GetAIAgentAsync();
+AIAgent a2aAgent = agentCard.GetAIAgent();
 
 // Create the main agent, and provide the a2a agent skills as a function tools.
 AIAgent agent = new AzureOpenAIClient(

dotnet/samples/GettingStarted/AgentOpenTelemetry/Program.cs

@@ -125,7 +125,7 @@ var agent = new ChatClientAgent(instrumentedChatClient,
     instructions: "You are a helpful assistant that provides concise and informative responses.",
     tools: [AIFunctionFactory.Create(GetWeatherAsync)])
     .AsBuilder()
-    .UseOpenTelemetry(SourceName) // enable telemetry at the agent level
+    .UseOpenTelemetry(SourceName, configure: (cfg) => cfg.EnableSensitiveData = true) // enable telemetry at the agent level
     .Build();
 
 var thread = agent.GetNewThread();
@@ -134,6 +134,8 @@ appLogger.LogInformation("Agent created successfully with ID: {AgentId}", agent.
 
 // Create a parent span for the entire agent session
 using var sessionActivity = activitySource.StartActivity("Agent Session");
+Console.WriteLine($"Trace ID: {sessionActivity?.TraceId} ");
+
 var sessionId = Guid.NewGuid().ToString("N");
 sessionActivity?
     .SetTag("agent.name", "OpenTelemetryDemoAgent")
@@ -147,7 +149,7 @@ using (appLogger.BeginScope(new Dictionary<string, object> { ["SessionId"] = ses
 
     while (true)
     {
-        Console.Write("You: ");
+        Console.Write("You (or 'exit' to quit): ");
         var userInput = Console.ReadLine();
 
         if (string.IsNullOrWhiteSpace(userInput) || userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))

dotnet/samples/GettingStarted/AgentProviders/Agent_With_AzureFoundryAgent/Agent_With_AzureFoundryAgent.csproj

@@ -14,7 +14,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
   </ItemGroup>
 
 </Project>

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/AgentWithRAG_Step01_BasicTextRAG.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <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.SemanticKernel.Connectors.InMemory" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/Program.cs

@@ -0,0 +1,105 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use TextSearchProvider to add retrieval augmented generation (RAG) capabilities to an AI agent.
+// The sample uses an In-Memory vector store, which can easily be replaced with any other vector store that implements the Microsoft.Extensions.VectorData abstractions.
+// The TextSearchProvider runs a search against the vector store via the TextSearchStore before each model invocation and injects the results into the model context.
+// The TextSearchStore is a sample store implementation that hardcodes a storage schema and uses the vector store to store and retrieve documents.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Data;
+using Microsoft.Agents.AI.Samples;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.VectorData;
+using Microsoft.SemanticKernel.Connectors.InMemory;
+using OpenAI;
+
+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 embeddingDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-3-large";
+
+AzureOpenAIClient azureOpenAIClient = new(
+    new Uri(endpoint),
+    new AzureCliCredential());
+
+// Create an In-Memory vector store that uses the Azure OpenAI embedding model to generate embeddings.
+VectorStore vectorStore = new InMemoryVectorStore(new()
+{
+    EmbeddingGenerator = azureOpenAIClient.GetEmbeddingClient(embeddingDeploymentName).AsIEmbeddingGenerator()
+});
+
+// Create a store that defines a storage schema, and uses the vector store to store and retrieve documents.
+TextSearchStore textSearchStore = new(vectorStore, "product-and-policy-info", 3072);
+
+// Upload sample documents into the store.
+await textSearchStore.UpsertDocumentsAsync(GetSampleDocuments());
+
+// Create an adapter function that the TextSearchProvider can use to run searches against the TextSearchStore.
+Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchResult>>> SearchAdapter = async (text, ct) =>
+{
+    // Here we are limiting the search results to the single top result to demonstrate that we are accurately matching
+    // specific search results for each question, but in a real world case, more results should be used.
+    var searchResults = await textSearchStore.SearchAsync(text, 1, ct);
+    return searchResults.Select(r => new TextSearchProvider.TextSearchResult
+    {
+        SourceName = r.SourceName,
+        SourceLink = r.SourceLink,
+        Text = r.Text ?? string.Empty,
+        RawRepresentation = r
+    });
+};
+
+// Configure the options for the TextSearchProvider.
+TextSearchProviderOptions textSearchOptions = new()
+{
+    // Run the search prior to every model invocation.
+    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
+};
+
+// Create the AI agent with the TextSearchProvider as the AI context provider.
+AIAgent agent = azureOpenAIClient
+    .GetChatClient(deploymentName)
+    .CreateAIAgent(new ChatClientAgentOptions
+    {
+        Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available.",
+        AIContextProviderFactory = ctx => new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)
+    });
+
+AgentThread thread = agent.GetNewThread();
+
+Console.WriteLine(">> Asking about returns\n");
+Console.WriteLine(await agent.RunAsync("Hi! I need help understanding the return policy.", thread));
+
+Console.WriteLine("\n>> Asking about shipping\n");
+Console.WriteLine(await agent.RunAsync("How long does standard shipping usually take?", thread));
+
+Console.WriteLine("\n>> Asking about product care\n");
+Console.WriteLine(await agent.RunAsync("What is the best way to maintain the TrailRunner tent fabric?", thread));
+
+// Produces some sample search documents.
+// Each one contains a source name and link, which the agent can use to cite sources in its responses.
+static IEnumerable<TextSearchDocument> GetSampleDocuments()
+{
+    yield return new TextSearchDocument
+    {
+        SourceId = "return-policy-001",
+        SourceName = "Contoso Outdoors Return Policy",
+        SourceLink = "https://contoso.com/policies/returns",
+        Text = "Customers may return any item within 30 days of delivery. Items should be unused and include original packaging. Refunds are issued to the original payment method within 5 business days of inspection."
+    };
+    yield return new TextSearchDocument
+    {
+        SourceId = "shipping-guide-001",
+        SourceName = "Contoso Outdoors Shipping Guide",
+        SourceLink = "https://contoso.com/help/shipping",
+        Text = "Standard shipping is free on orders over $50 and typically arrives in 3-5 business days within the continental United States. Expedited options are available at checkout."
+    };
+    yield return new TextSearchDocument
+    {
+        SourceId = "tent-care-001",
+        SourceName = "TrailRunner Tent Care Instructions",
+        SourceLink = "https://contoso.com/manuals/trailrunner-tent",
+        Text = "Clean the tent fabric with lukewarm water and a non-detergent soap. Allow it to air dry completely before storage and avoid prolonged UV exposure to extend the lifespan of the waterproof coating."
+    };
+}

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/TextSearchStore/TextSearchDocument.cs

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.Samples;
+
+/// <summary>
+/// Represents a document that can be used for Retrieval Augmented Generation (RAG) that stores textual data.
+/// </summary>
+public sealed class TextSearchDocument
+{
+    /// <summary>
+    /// Gets or sets an optional list of namespaces that the document should belong to.
+    /// </summary>
+    /// <remarks>
+    /// A namespace is a logical grouping of documents, e.g. may include a group id to scope the document to a specific group of users.
+    /// </remarks>
+    public IList<string> Namespaces { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets the content as text.
+    /// </summary>
+    public string? Text { get; set; }
+
+    /// <summary>
+    /// Gets or sets an optional source ID for the document.
+    /// </summary>
+    /// <remarks>
+    /// This ID should be unique within the collection that the document is stored in, and can
+    /// be used to map back to the source artifact for this document.
+    /// If updates need to be made later or the source document was deleted and this document
+    /// also needs to be deleted, this id can be used to find the document again.
+    /// </remarks>
+    public string? SourceId { get; set; }
+
+    /// <summary>
+    /// Gets or sets an optional name for the source document.
+    /// </summary>
+    /// <remarks>
+    /// This can be used to provide display names for citation links when the document is referenced as
+    /// part of a response to a query.
+    /// </remarks>
+    public string? SourceName { get; set; }
+
+    /// <summary>
+    /// Gets or sets an optional link back to the source of the document.
+    /// </summary>
+    /// <remarks>
+    /// This can be used to provide citation links when the document is referenced as
+    /// part of a response to a query.
+    /// </remarks>
+    public string? SourceLink { get; set; }
+}

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/TextSearchStore/TextSearchStore.cs

@@ -0,0 +1,392 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Linq.Expressions;
+using System.Text.RegularExpressions;
+using Microsoft.Extensions.VectorData;
+
+namespace Microsoft.Agents.AI.Samples;
+
+/// <summary>
+/// A class that allows for easy storage and retrieval of documents in a Vector Store for Retrieval Augmented Generation (RAG).
+/// </summary>
+/// <remarks>
+/// <para>
+/// This class provides an opinionated schema for storing documents in a vector store. It is valuable for simple scenarios
+/// where you want to store text + embedding, or a reference to an external document + embedding without needing to customize the schema.
+/// If you want to control the schema yourself, use an implementation of <see cref="VectorStoreCollection{TKey, TRecord}"/> directly instead.
+/// </para>
+/// <para>
+/// This class and its related types are currently provided as a sample implementation, but may be promoted to a first-class supported API in future releases.
+/// </para>
+/// </remarks>
+public sealed partial class TextSearchStore : IDisposable
+{
+#if NET
+    [GeneratedRegex(@"\p{L}+", RegexOptions.IgnoreCase, "en-US")]
+    private static partial Regex AnyLanguageWordRegex();
+
+    private static readonly Func<string, ICollection<string>> s_defaultWordSegmenter = text => AnyLanguageWordRegex().Matches(text).Select(x => x.Value).ToList();
+#else
+    private static readonly Regex s_anyLanguageWordRegex = new(@"\p{L}+", RegexOptions.Compiled);
+    private static Regex AnyLanguageWordRegex() => s_anyLanguageWordRegex;
+
+    private static readonly Func<string, ICollection<string>> s_defaultWordSegmenter = text =>
+    {
+        List<string> words = new();
+        foreach (Match word in AnyLanguageWordRegex().Matches(text))
+        {
+            words.Add(word.Value);
+        }
+        return words;
+    };
+#endif
+
+    private readonly VectorStore _vectorStore;
+    private readonly TextSearchStoreOptions _options;
+    private readonly Func<string, ICollection<string>> _wordSegmenter;
+
+    private readonly VectorStoreCollection<object, Dictionary<string, object?>> _vectorStoreRecordCollection;
+    private readonly SemaphoreSlim _collectionInitializationLock = new(1, 1);
+    private bool _collectionInitialized;
+    private bool _disposedValue;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TextSearchStore"/> class.
+    /// </summary>
+    /// <param name="vectorStore">The vector store to store and read the memories from.</param>
+    /// <param name="collectionName">The name of the collection in the vector store to store and read the memories from.</param>
+    /// <param name="vectorDimensions">The number of dimensions to use for the memory embeddings.</param>
+    /// <param name="options">Options to configure the behavior of this class.</param>
+    /// <exception cref="NotSupportedException">Thrown if the key type provided is not supported.</exception>
+    public TextSearchStore(
+        VectorStore vectorStore,
+        string collectionName,
+        int vectorDimensions,
+        TextSearchStoreOptions? options = default)
+    {
+        // Verify
+        if (vectorStore is null)
+        {
+            throw new ArgumentNullException(nameof(vectorStore));
+        }
+
+        if (string.IsNullOrWhiteSpace(collectionName))
+        {
+            throw new ArgumentException("Collection name cannot be null or whitespace.", nameof(collectionName));
+        }
+
+        if (vectorDimensions < 1)
+        {
+            throw new ArgumentOutOfRangeException(nameof(vectorDimensions), "Vector dimensions must be greater than zero.");
+        }
+
+        if (options?.KeyType is not null && options.KeyType != typeof(string) && options.KeyType != typeof(Guid))
+        {
+            throw new NotSupportedException($"Unsupported key of type '{options.KeyType.Name}'");
+        }
+
+        if (options?.KeyType is not null && options.KeyType != typeof(string) && options?.UseSourceIdAsPrimaryKey is true)
+        {
+            throw new NotSupportedException($"The {nameof(TextSearchStoreOptions.UseSourceIdAsPrimaryKey)} option can only be used when the key type is 'string'.");
+        }
+
+        // Assign
+        this._vectorStore = vectorStore;
+        this._options = options ?? new TextSearchStoreOptions();
+        this._wordSegmenter = this._options.WordSegmenter ?? s_defaultWordSegmenter;
+
+        // Create a definition so that we can use the dimensions provided at runtime.
+        VectorStoreCollectionDefinition ragDocumentDefinition = new()
+        {
+            Properties = new List<VectorStoreProperty>()
+            {
+                new VectorStoreKeyProperty("Key", this._options.KeyType ?? typeof(string)),
+                new VectorStoreDataProperty("Namespaces", typeof(List<string>)) { IsIndexed = true },
+                new VectorStoreDataProperty("SourceId", typeof(string)) { IsIndexed = true },
+                new VectorStoreDataProperty("Text", typeof(string)) { IsFullTextIndexed = true },
+                new VectorStoreDataProperty("SourceName", typeof(string)),
+                new VectorStoreDataProperty("SourceLink", typeof(string)),
+                new VectorStoreVectorProperty("TextEmbedding", typeof(string), vectorDimensions),
+            }
+        };
+
+        this._vectorStoreRecordCollection = this._vectorStore.GetDynamicCollection(collectionName, ragDocumentDefinition);
+    }
+
+    /// <summary>
+    /// Upserts a batch of text chunks into the vector store.
+    /// </summary>
+    /// <param name="textChunks">The text chunks to upload.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that completes when the documents have been upserted.</returns>
+    public async Task UpsertTextAsync(IEnumerable<string> textChunks, CancellationToken cancellationToken = default)
+    {
+        if (textChunks == null)
+        {
+            throw new ArgumentNullException(nameof(textChunks));
+        }
+
+        var vectorStoreRecordCollection = await this.EnsureCollectionExistsAsync(cancellationToken).ConfigureAwait(false);
+
+        var storageDocuments = textChunks.Select(textChunk =>
+        {
+            // Without text we cannot generate a vector.
+            if (string.IsNullOrWhiteSpace(textChunk))
+            {
+                throw new ArgumentException("One of the provided text chunks is null.", nameof(textChunks));
+            }
+
+            return new Dictionary<string, object?>
+            {
+                { "Key", this.GenerateUniqueKey(null) },
+                { "Namespaces", new List<string>() },
+                { "Text", textChunk },
+                { "TextEmbedding", textChunk },
+            };
+        });
+
+        await vectorStoreRecordCollection.UpsertAsync(storageDocuments, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Upserts a batch of documents into the vector store.
+    /// </summary>
+    /// <param name="documents">The documents to upload.</param>
+    /// <param name="options">Optional options to control the upsert behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that completes when the documents have been upserted.</returns>
+    public async Task UpsertDocumentsAsync(IEnumerable<TextSearchDocument> documents, TextSearchStoreUpsertOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        if (documents is null)
+        {
+            throw new ArgumentNullException(nameof(documents));
+        }
+
+        var vectorStoreRecordCollection = await this.EnsureCollectionExistsAsync(cancellationToken).ConfigureAwait(false);
+
+        var storageDocuments = documents.Select(document =>
+        {
+            if (document is null)
+            {
+                throw new ArgumentNullException(nameof(documents), "One of the provided documents is null.");
+            }
+
+            // Without text we cannot generate a vector.
+            if (string.IsNullOrWhiteSpace(document.Text))
+            {
+                throw new ArgumentException($"The {nameof(TextSearchDocument.Text)} property must be set.", nameof(document));
+            }
+
+            // If we aren't persisting the text, we need a source id or link to refer back to the original document.
+            if (options?.DoNotPersistSourceText is true && string.IsNullOrWhiteSpace(document.SourceId) && string.IsNullOrWhiteSpace(document.SourceLink))
+            {
+                throw new ArgumentException($"Either the {nameof(TextSearchDocument.SourceId)} or {nameof(TextSearchDocument.SourceLink)} properties must be set when the {nameof(TextSearchStoreUpsertOptions.DoNotPersistSourceText)} setting is true.", nameof(document));
+            }
+
+            var key = this.GenerateUniqueKey(this._options.UseSourceIdAsPrimaryKey ?? false ? document.SourceId : null);
+
+            return new Dictionary<string, object?>()
+            {
+                { "Key", key },
+                { "Namespaces", document.Namespaces.ToList() },
+                { "SourceId", document.SourceId },
+                { "Text", options?.DoNotPersistSourceText is true ? null : document.Text },
+                { "SourceName", document.SourceName },
+                { "SourceLink", document.SourceLink },
+                { "TextEmbedding", document.Text },
+            };
+        });
+
+        await vectorStoreRecordCollection.UpsertAsync(storageDocuments, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Search the database for documents similar to the provided query.
+    /// </summary>
+    /// <param name="query">The text query to find similar documents to.</param>
+    /// <param name="top">The maximum number of results to return.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The search results.</returns>
+    public async Task<IEnumerable<TextSearchDocument>> SearchAsync(string query, int top, CancellationToken cancellationToken = default)
+    {
+        var searchResult = await this.SearchCoreAsync(query, top, cancellationToken).ConfigureAwait(false);
+
+        return searchResult.Select(x => new TextSearchDocument()
+        {
+            Namespaces = (List<string>)x["Namespaces"]!,
+            Text = (string?)x["Text"],
+            SourceId = (string?)x["SourceId"],
+            SourceName = (string?)x["SourceName"],
+            SourceLink = (string?)x["SourceLink"],
+        });
+    }
+
+    /// <summary>
+    /// Internal search implementation with hydration of id / link only storage.
+    /// </summary>
+    /// <param name="query">The text query to find similar documents to.</param>
+    /// <param name="top">The maximum number of results to return.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The search results.</returns>
+    private async Task<IEnumerable<Dictionary<string, object?>>> SearchCoreAsync(string query, int top, CancellationToken cancellationToken = default)
+    {
+        // Short circuit if the query is empty.
+        if (string.IsNullOrWhiteSpace(query))
+        {
+            return [];
+        }
+
+        var vectorStoreRecordCollection = await this.EnsureCollectionExistsAsync(cancellationToken).ConfigureAwait(false);
+
+        // If the user has not opted out of hybrid search, check if the vector store supports it.
+        var hybridSearchCollection = this._options.UseHybridSearch ?? true ?
+            vectorStoreRecordCollection.GetService(typeof(IKeywordHybridSearchable<Dictionary<string, object?>>)) as IKeywordHybridSearchable<Dictionary<string, object?>> :
+            null;
+
+        // Optional filter to limit the search to a specific namespace.
+        Expression<Func<Dictionary<string, object?>, bool>>? filter = string.IsNullOrWhiteSpace(this._options.SearchNamespace) ? null : x => ((List<string>)x["Namespaces"]!).Contains(this._options.SearchNamespace);
+
+        // Execute a hybrid search if possible, otherwise perform a regular vector search.
+        var searchResult = hybridSearchCollection is null
+            ? vectorStoreRecordCollection.SearchAsync(
+                query,
+                top,
+                options: new()
+                {
+                    Filter = filter,
+                },
+                cancellationToken: cancellationToken)
+            : hybridSearchCollection.HybridSearchAsync(
+                query,
+                this._wordSegmenter(query),
+                top,
+                options: new()
+                {
+                    Filter = filter,
+                },
+                cancellationToken: cancellationToken);
+
+        // Retrieve the documents from the search results.
+        List<Dictionary<string, object?>> searchResponseDocs = new();
+        await foreach (var searchResponseDoc in searchResult.WithCancellation(cancellationToken).ConfigureAwait(false))
+        {
+            searchResponseDocs.Add(searchResponseDoc.Record);
+        }
+
+        // Find any source ids and links for which the text needs to be retrieved.
+        var sourceIdsToRetrieve = searchResponseDocs
+            .Where(x => string.IsNullOrWhiteSpace((string?)x["Text"]))
+            .Select(x => new TextSearchStoreOptions.SourceRetrievalRequest((string?)x["SourceId"], (string?)x["SourceLink"]))
+            .ToList();
+
+        // If we have none, we can return early.
+        if (sourceIdsToRetrieve.Count == 0)
+        {
+            return searchResponseDocs;
+        }
+
+        if (this._options.SourceRetrievalCallback is null)
+        {
+            throw new InvalidOperationException($"The {nameof(TextSearchStoreOptions.SourceRetrievalCallback)} option must be set if retrieving documents without stored text.");
+        }
+
+        // Retrieve the source text for the documents that need it.
+        var retrievalResponses = await this._options.SourceRetrievalCallback(sourceIdsToRetrieve).ConfigureAwait(false);
+
+        if (retrievalResponses is null)
+        {
+            throw new InvalidOperationException($"The {nameof(TextSearchStoreOptions.SourceRetrievalCallback)} must return a non-null value.");
+        }
+
+        // Update the retrieved documents with the retrieved text.
+        return searchResponseDocs.GroupJoin(
+            retrievalResponses,
+            searchResponseDoc => (searchResponseDoc["SourceId"], searchResponseDoc["SourceLink"]),
+            retrievalResponse => (retrievalResponse.SourceId, retrievalResponse.SourceLink),
+            (searchResponseDoc, textRetrievalResponse) => (searchResponseDoc, textRetrievalResponse))
+            .SelectMany(
+                joinedSet => joinedSet.textRetrievalResponse.DefaultIfEmpty(),
+                (combined, textRetrievalResponse) =>
+                {
+                    combined.searchResponseDoc["Text"] = textRetrievalResponse?.Text ?? combined.searchResponseDoc["Text"];
+                    return combined.searchResponseDoc;
+                });
+    }
+
+    /// <summary>
+    /// Thread safe method to get the collection and ensure that it is created at least once.
+    /// </summary>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>The created collection.</returns>
+    private async Task<VectorStoreCollection<object, Dictionary<string, object?>>> EnsureCollectionExistsAsync(CancellationToken cancellationToken)
+    {
+        // Return immediately if the collection is already created, no need to do any locking in this case.
+        if (this._collectionInitialized)
+        {
+            return this._vectorStoreRecordCollection;
+        }
+
+        // Wait on a lock to ensure that only one thread can create the collection.
+        await this._collectionInitializationLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+
+        // If multiple threads waited on the lock, and the first already created the collection,
+        // we can return immediately without doing any work in subsequent threads.
+        if (this._collectionInitialized)
+        {
+            this._collectionInitializationLock.Release();
+            return this._vectorStoreRecordCollection;
+        }
+
+        // Only the winning thread should reach this point and create the collection.
+        try
+        {
+            await this._vectorStoreRecordCollection.EnsureCollectionExistsAsync(cancellationToken).ConfigureAwait(false);
+            this._collectionInitialized = true;
+        }
+        finally
+        {
+            this._collectionInitializationLock.Release();
+        }
+
+        return this._vectorStoreRecordCollection;
+    }
+
+    /// <summary>
+    /// Generates a unique key for the RAG document.
+    /// </summary>
+    /// <param name="sourceId">Source id of the source document for this RAG document.</param>
+    /// <returns>A new unique key.</returns>
+    /// <exception cref="NotSupportedException">Thrown if the requested key type is not supported.</exception>
+    private object GenerateUniqueKey(string? sourceId)
+        => this._options.KeyType switch
+        {
+            _ when (this._options.KeyType == null || this._options.KeyType == typeof(string)) && !string.IsNullOrWhiteSpace(sourceId) => sourceId!,
+            _ when this._options.KeyType == null || this._options.KeyType == typeof(string) => Guid.NewGuid().ToString(),
+            _ when this._options.KeyType == typeof(Guid) => Guid.NewGuid(),
+
+            _ => throw new NotSupportedException($"Unsupported key of type '{this._options.KeyType.Name}'")
+        };
+
+    /// <inheritdoc/>
+    private void Dispose(bool disposing)
+    {
+        if (!this._disposedValue)
+        {
+            if (disposing)
+            {
+                this._vectorStoreRecordCollection.Dispose();
+                this._collectionInitializationLock.Dispose();
+            }
+
+            this._disposedValue = true;
+        }
+    }
+
+    /// <inheritdoc/>
+    public void Dispose()
+    {
+        // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method
+        this.Dispose(disposing: true);
+        GC.SuppressFinalize(this);
+    }
+}

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/TextSearchStore/TextSearchStoreOptions.cs

@@ -0,0 +1,140 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.Samples;
+
+/// <summary>
+/// Contains options for the <see cref="TextSearchStore"/>.
+/// </summary>
+public sealed class TextSearchStoreOptions
+{
+    /// <summary>
+    /// Gets or sets an optional namespace to pre-filter the possible
+    /// records with when doing a vector search.
+    /// </summary>
+    public string? SearchNamespace { get; init; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to use the source ID as the primary key for records.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Using the source ID as the primary key allows for easy updates from the source for any changed
+    /// records, since those records can just be upserted again, and will overwrite the previous version
+    /// of the same record.
+    /// </para>
+    /// <para>
+    /// This setting can only be used when the chosen key type is a string.
+    /// </para>
+    /// </remarks>
+    /// <value>
+    /// Defaults to <c>false</c> if not set.
+    /// </value>
+    public bool? UseSourceIdAsPrimaryKey { get; init; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether to use hybrid search if it is available for the provided vector store.
+    /// </summary>
+    /// <value>
+    /// Defaults to <c>true</c> if not set.
+    /// </value>
+    public bool? UseHybridSearch { get; init; }
+
+    /// <summary>
+    /// Gets or sets a word segmenter function to split search text into separate words for the purposes of hybrid search.
+    /// This will not be used if <see cref="UseHybridSearch"/> is set to <c>false</c>.
+    /// </summary>
+    /// <remarks>
+    /// Defaults to a simple text-character-based segmenter that splits the text by any character that is not a text character.
+    /// </remarks>
+    public Func<string, ICollection<string>>? WordSegmenter { get; init; }
+
+    /// <summary>
+    /// Gets or sets the type of key to use for records in the text search store.
+    /// </summary>
+    /// <remarks>
+    /// Make sure to pick a key type that is supported by the underlying vector store.
+    /// Note that you have to choose <see cref="string"/> when using <see cref="UseSourceIdAsPrimaryKey"/>.
+    /// </remarks>
+    /// <value>Defaults to <see cref="string"/> if not set. Only <see cref="string"/> and <see cref="Guid"/> is currently supported.</value>
+    public Type? KeyType { get; init; }
+
+    /// <summary>
+    /// Gets or sets an optional callback to load the source text using the source id or source link
+    /// if the source text is not persisted in the database.
+    /// </summary>
+    /// <remarks>
+    /// The response should include the source id or source link, as provided in the request,
+    /// plus the source text loaded from the source.
+    /// </remarks>
+    public Func<List<SourceRetrievalRequest>, Task<IEnumerable<SourceRetrievalResponse>>>? SourceRetrievalCallback { get; init; }
+
+    /// <summary>
+    /// Represents a request to the <see cref="SourceRetrievalCallback"/>.
+    /// </summary>
+    public sealed class SourceRetrievalRequest
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SourceRetrievalRequest"/> class.
+        /// </summary>
+        /// <param name="sourceId">The source ID of the document to retrieve.</param>
+        /// <param name="sourceLink">The source link of the document to retrieve.</param>
+        public SourceRetrievalRequest(string? sourceId, string? sourceLink)
+        {
+            this.SourceId = sourceId;
+            this.SourceLink = sourceLink;
+        }
+
+        /// <summary>
+        /// Gets or sets the source ID of the document to retrieve.
+        /// </summary>
+        public string? SourceId { get; set; }
+
+        /// <summary>
+        /// Gets or sets the source link of the document to retrieve.
+        /// </summary>
+        public string? SourceLink { get; set; }
+    }
+
+    /// <summary>
+    /// Represents a response from the <see cref="SourceRetrievalCallback"/>.
+    /// </summary>
+    public sealed class SourceRetrievalResponse
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="SourceRetrievalResponse"/> class.
+        /// </summary>
+        /// <param name="request">The request matching this response.</param>
+        /// <param name="text">The source text that was retrieved.</param>
+        public SourceRetrievalResponse(SourceRetrievalRequest request, string text)
+        {
+            if (request == null)
+            {
+                throw new ArgumentNullException(nameof(request));
+            }
+
+            if (text == null)
+            {
+                throw new ArgumentNullException(nameof(text));
+            }
+
+            this.SourceId = request.SourceId;
+            this.SourceLink = request.SourceLink;
+            this.Text = text;
+        }
+
+        /// <summary>
+        /// Gets or sets the source ID of the document that was retrieved.
+        /// </summary>
+        public string? SourceId { get; set; }
+
+        /// <summary>
+        /// Gets or sets the source link of the document that was retrieved.
+        /// </summary>
+        public string? SourceLink { get; set; }
+
+        /// <summary>
+        /// Gets or sets the source text of the document that was retrieved.
+        /// </summary>
+        public string Text { get; set; }
+    }
+}

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/TextSearchStore/TextSearchStoreUpsertOptions.cs

@@ -0,0 +1,17 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.Samples;
+
+/// <summary>
+/// Contains options for <see cref="TextSearchStore.UpsertDocumentsAsync(IEnumerable{TextSearchDocument}, TextSearchStoreUpsertOptions?, CancellationToken)"/>.
+/// </summary>
+public sealed class TextSearchStoreUpsertOptions
+{
+    /// <summary>
+    /// Gets or sets a value indicating whether the source text should be persisted in the database.
+    /// </summary>
+    /// <value>
+    /// Defaults to <see langword="false"/> if not set.
+    /// </value>
+    public bool DoNotPersistSourceText { get; init; }
+}

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_ExternalDataSourceRAG/AgentWithRAG_Step02_ExternalDataSourceRAG.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <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.SemanticKernel.Connectors.Qdrant" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_ExternalDataSourceRAG/Program.cs

@@ -0,0 +1,132 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use Qdrant to add retrieval augmented generation (RAG) capabilities to an AI agent.
+// While the sample is using Qdrant, it can easily be replaced with any other vector store that implements the Microsoft.Extensions.VectorData abstractions.
+// The TextSearchProvider runs a search against the vector store before each model invocation and injects the results into the model context.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Data;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.VectorData;
+using Microsoft.SemanticKernel.Connectors.Qdrant;
+using OpenAI;
+using Qdrant.Client;
+
+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 embeddingDeploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME") ?? "text-embedding-3-large";
+var afOverviewUrl = "https://github.com/MicrosoftDocs/semantic-kernel-docs/blob/main/agent-framework/overview/agent-framework-overview.md";
+var afMigrationUrl = "https://raw.githubusercontent.com/MicrosoftDocs/semantic-kernel-docs/refs/heads/main/agent-framework/migration-guide/from-semantic-kernel/index.md";
+
+AzureOpenAIClient azureOpenAIClient = new(
+    new Uri(endpoint),
+    new AzureCliCredential());
+
+// Create a Qdrant vector store that uses the Azure OpenAI embedding model to generate embeddings.
+QdrantClient client = new("localhost");
+VectorStore vectorStore = new QdrantVectorStore(client, ownsClient: true, new()
+{
+    EmbeddingGenerator = azureOpenAIClient.GetEmbeddingClient(embeddingDeploymentName).AsIEmbeddingGenerator()
+});
+
+// Create a collection and upsert some text into it.
+var documentationCollection = vectorStore.GetCollection<Guid, DocumentationChunk>("documentation");
+await documentationCollection.EnsureCollectionDeletedAsync(); // Clear out any data from previous runs.
+await documentationCollection.EnsureCollectionExistsAsync();
+await UploadDataFromMarkdown(afOverviewUrl, "Microsoft Agent Framework Overview", documentationCollection, 2000, 200);
+await UploadDataFromMarkdown(afMigrationUrl, "Semantic Kernel to Microsoft Agent Framework Migration Guide", documentationCollection, 2000, 200);
+
+// Create an adapter function that the TextSearchProvider can use to run searches against the collection.
+Func<string, CancellationToken, Task<IEnumerable<TextSearchProvider.TextSearchResult>>> SearchAdapter = async (text, ct) =>
+{
+    List<TextSearchProvider.TextSearchResult> results = [];
+    await foreach (var result in documentationCollection.SearchAsync(text, 5, cancellationToken: ct))
+    {
+        results.Add(new TextSearchProvider.TextSearchResult
+        {
+            SourceName = result.Record.SourceName,
+            SourceLink = result.Record.SourceLink,
+            Text = result.Record.Text ?? string.Empty,
+            RawRepresentation = result
+        });
+    }
+    return results;
+};
+
+// Configure the options for the TextSearchProvider.
+TextSearchProviderOptions textSearchOptions = new()
+{
+    // Run the search prior to every model invocation.
+    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
+    // Use up to 4 recent messages when searching so that searches
+    // still produce valuable results even when the user is referring
+    // back to previous messages in their request.
+    RecentMessageMemoryLimit = 5
+};
+
+// Create the AI agent with the TextSearchProvider as the AI context provider.
+AIAgent agent = azureOpenAIClient
+    .GetChatClient(deploymentName)
+    .CreateAIAgent(new ChatClientAgentOptions
+    {
+        Instructions = "You are a helpful support specialist for the Microsoft Agent Framework. Answer questions using the provided context and cite the source document when available. Keep responses brief.",
+        AIContextProviderFactory = ctx => new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)
+    });
+
+AgentThread thread = agent.GetNewThread();
+
+Console.WriteLine(">> Asking about SK threads\n");
+Console.WriteLine(await agent.RunAsync("Hi! How do I create a thread in Semantic Kernel?", thread));
+
+// Here we are asking a very vague question when taken out of context,
+// but since we are including previous messages in our search using RecentMessageMemoryLimit
+// the RAG search should still produce useful results.
+Console.WriteLine("\n>> Asking about AF threads\n");
+Console.WriteLine(await agent.RunAsync("and in Agent Framework?", thread));
+
+Console.WriteLine("\n>> Contrasting Approaches\n");
+Console.WriteLine(await agent.RunAsync("Please contrast the two approaches", thread));
+
+Console.WriteLine("\n>> Asking about ancestry\n");
+Console.WriteLine(await agent.RunAsync("What are the predecessors to the Agent Framework?", thread));
+
+static async Task UploadDataFromMarkdown(string markdownUrl, string sourceName, VectorStoreCollection<Guid, DocumentationChunk> vectorStoreCollection, int chunkSize, int overlap)
+{
+    // Download the markdown from the given url.
+    using HttpClient client = new();
+    var markdown = await client.GetStringAsync(new Uri(markdownUrl));
+
+    // Chunk it into separate parts with some overlap between chunks
+    var chunks = new List<DocumentationChunk>();
+    for (int i = 0; i < markdown.Length; i += chunkSize)
+    {
+        var chunk = new DocumentationChunk
+        {
+            Key = Guid.NewGuid(),
+            SourceLink = markdownUrl,
+            SourceName = sourceName,
+            Text = markdown.Substring(i, Math.Min(chunkSize + overlap, markdown.Length - i))
+        };
+        chunks.Add(chunk);
+    }
+
+    // Upsert each chunk into the provided vector store.
+    await vectorStoreCollection.UpsertAsync(chunks);
+}
+
+// Data model that defines the database schema we want to use.
+internal sealed class DocumentationChunk
+{
+    [VectorStoreKey]
+    public Guid Key { get; set; }
+    [VectorStoreData]
+    public string SourceLink { get; set; } = string.Empty;
+    [VectorStoreData]
+    public string SourceName { get; set; } = string.Empty;
+    [VectorStoreData]
+    public string Text { get; set; } = string.Empty;
+    [VectorStoreVector(Dimensions: 3072)]
+    public string Embedding => this.Text;
+}

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_ExternalDataSourceRAG/README.md

@@ -0,0 +1,60 @@
+# Agent Framework Retrieval Augmented Generation (RAG) with an external Vector Store with a custom schema
+
+This sample demonstrates how to create and run an agent that uses Retrieval Augmented Generation (RAG) with an external vector store.
+It also uses a custom schema for the documents stored in the vector store.
+This sample uses Qdrant for the vector store, but this can easily be swapped out for any vector store that has a Microsoft.Extensions.VectorStore implementation.
+
+## Prerequisites
+
+- .NET 8.0 SDK or later
+- Azure OpenAI service endpoint
+- Both a chat completion and embedding deployment configured in the Azure OpenAI resource
+- Azure CLI installed and authenticated (for Azure credential authentication)
+- User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource.
+- An existing Qdrant instance. You can use a managed service or run a local instance using Docker, but the sample assumes the instance is running locally.
+
+**Note**: These samples use 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**: These samples use 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).
+
+## Running the sample from the console
+
+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
+$env:AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME="text-embedding-3-large"  # Optional, defaults to text-embedding-3-large
+```
+
+If the variables are not set, you will be prompted for the values when running the samples.
+
+To use Qdrant in docker locally, start your Qdrant instance using the default port mappings.
+
+```powershell
+docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant:latest
+```
+
+Execute the following command to build the sample:
+
+```powershell
+dotnet build
+```
+
+Execute the following command to run the sample:
+
+```powershell
+dotnet run --no-build
+```
+
+Or just build and run in one step:
+
+```powershell
+dotnet run
+```
+
+## Running the sample from Visual Studio
+
+Open the solution in Visual Studio and set the sample project as the startup project. Then, run the project using the built-in debugger or by pressing `F5`.
+
+You will be prompted for any required environment variables if they are not already set.

dotnet/samples/GettingStarted/AgentWithRAG/README.md

@@ -0,0 +1,8 @@
+# Agent Framework Retrieval Augmented Generation (RAG)
+
+These samples show how to create an agent with the Agent Framework that uses Retrieval Augmented Generation (RAG) to enhance its responses with information from a knowledge base.
+
+|Sample|Description|
+|---|---|
+|[Basic Text RAG](./AgentWithRAG_Step01_BasicTextRAG/)|This sample demonstrates how to create and run a basic agent with simple text Retrieval Augmented Generation (RAG).|
+|[RAG with external Vector Store and custom schema](./AgentWithRAG_Step02_ExternalDataSourceRAG/)|This sample demonstrates how to create and run an agent that uses Retrieval Augmented Generation (RAG) with an external vector store. It also uses a custom schema for the documents stored in the vector store.|

dotnet/samples/GettingStarted/Agents/Agent_Step10_AsMcpTool/Agent_Step10_AsMcpTool.csproj

@@ -18,7 +18,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
   </ItemGroup>
   
 </Project>

dotnet/samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/Agent_Step17_BackgroundResponses.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </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>
+  
+</Project>

dotnet/samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/Program.cs

@@ -0,0 +1,70 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use background responses with ChatClientAgent and Azure OpenAI Responses.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using OpenAI;
+
+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())
+     .GetOpenAIResponseClient(deploymentName)
+     .CreateAIAgent();
+
+// Enable background responses (only supported by OpenAI Responses at this time).
+AgentRunOptions options = new() { AllowBackgroundResponses = true };
+
+AgentThread thread = agent.GetNewThread();
+
+// Start the initial run.
+AgentRunResponse response = await agent.RunAsync("Write a very long novel about otters in space.", thread, options);
+
+// Poll until the response is complete.
+while (response.ContinuationToken is { } token)
+{
+    // Wait before polling again.
+    await Task.Delay(TimeSpan.FromSeconds(2));
+
+    // Continue with the token.
+    options.ContinuationToken = token;
+
+    response = await agent.RunAsync(thread, options);
+}
+
+// Display the result.
+Console.WriteLine(response.Text);
+
+// Reset options and thread for streaming.
+options = new() { AllowBackgroundResponses = true };
+thread = agent.GetNewThread();
+
+AgentRunResponseUpdate? lastReceivedUpdate = null;
+// Start streaming.
+await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync("Write a very long novel about otters in space.", thread, options))
+{
+    // Output each update.
+    Console.Write(update.Text);
+
+    // Track last update.
+    lastReceivedUpdate = update;
+
+    // Simulate connection loss after first piece of content received.
+    if (update.Text.Length > 0)
+    {
+        break;
+    }
+}
+
+// Resume from interruption point.
+options.ContinuationToken = lastReceivedUpdate?.ContinuationToken;
+
+await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(thread, options))
+{
+    // Output each update.
+    Console.Write(update.Text);
+}

dotnet/samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/README.md

@@ -0,0 +1,27 @@
+# What This Sample Shows
+
+This sample demonstrates how to use background responses with ChatCompletionAgent and Azure OpenAI Responses for long-running operations. Background responses support:
+
+- **Polling for completion** - Non-streaming APIs can start a background operation and return a continuation token. Poll with the token until the response completes.
+- **Resuming after interruption** - Streaming APIs can be interrupted and resumed from the last update using the continuation token.
+
+> **Note:** Background responses are currently only supported by OpenAI Responses.
+
+For more information, see the [official documentation](https://learn.microsoft.com/en-us/agent-framework/user-guide/agents/agent-background-responses?pivots=programming-language-csharp).
+
+# Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 8.0 SDK or later
+- Azure OpenAI 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 OpenAI 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_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
+```

dotnet/samples/GettingStarted/Agents/Agent_Step18_TextSearchRag/Agent_Step18_TextSearchRag.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/Agents/Agent_Step18_TextSearchRag/Program.cs

@@ -0,0 +1,82 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to use TextSearchProvider to add retrieval augmented generation (RAG)
+// capabilities to an AI agent. The provider runs a search against an external knowledge base
+// before each model invocation and injects the results into the model context.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Data;
+using Microsoft.Extensions.AI;
+using OpenAI;
+
+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";
+
+TextSearchProviderOptions textSearchOptions = new()
+{
+    // Run the search prior to every model invocation and keep a short rolling window of conversation context.
+    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
+    RecentMessageMemoryLimit = 6,
+};
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new AzureCliCredential())
+    .GetChatClient(deploymentName)
+    .CreateAIAgent(new ChatClientAgentOptions
+    {
+        Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available.",
+        AIContextProviderFactory = ctx => new TextSearchProvider(MockSearchAsync, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)
+    });
+
+AgentThread thread = agent.GetNewThread();
+
+Console.WriteLine(">> Asking about returns\n");
+Console.WriteLine(await agent.RunAsync("Hi! I need help understanding the return policy.", thread));
+
+Console.WriteLine("\n>> Asking about shipping\n");
+Console.WriteLine(await agent.RunAsync("How long does standard shipping usually take?", thread));
+
+Console.WriteLine("\n>> Asking about product care\n");
+Console.WriteLine(await agent.RunAsync("What is the best way to maintain the TrailRunner tent fabric?", thread));
+
+static Task<IEnumerable<TextSearchProvider.TextSearchResult>> MockSearchAsync(string query, CancellationToken cancellationToken)
+{
+    // The mock search inspects the user's question and returns pre-defined snippets
+    // that resemble documents stored in an external knowledge source.
+    List<TextSearchProvider.TextSearchResult> results = new();
+
+    if (query.Contains("return", StringComparison.OrdinalIgnoreCase) || query.Contains("refund", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "Contoso Outdoors Return Policy",
+            SourceLink = "https://contoso.com/policies/returns",
+            Text = "Customers may return any item within 30 days of delivery. Items should be unused and include original packaging. Refunds are issued to the original payment method within 5 business days of inspection."
+        });
+    }
+
+    if (query.Contains("shipping", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "Contoso Outdoors Shipping Guide",
+            SourceLink = "https://contoso.com/help/shipping",
+            Text = "Standard shipping is free on orders over $50 and typically arrives in 3-5 business days within the continental United States. Expedited options are available at checkout."
+        });
+    }
+
+    if (query.Contains("tent", StringComparison.OrdinalIgnoreCase) || query.Contains("fabric", StringComparison.OrdinalIgnoreCase))
+    {
+        results.Add(new()
+        {
+            SourceName = "TrailRunner Tent Care Instructions",
+            SourceLink = "https://contoso.com/manuals/trailrunner-tent",
+            Text = "Clean the tent fabric with lukewarm water and a non-detergent soap. Allow it to air dry completely before storage and avoid prolonged UV exposure to extend the lifespan of the waterproof coating."
+        });
+    }
+
+    return Task.FromResult<IEnumerable<TextSearchProvider.TextSearchResult>>(results);
+}

dotnet/samples/GettingStarted/Agents/Agent_Step19_Mem0Provider/Agent_Step19_Mem0Provider.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Mem0\Microsoft.Agents.AI.Mem0.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/Agents/Agent_Step19_Mem0Provider/Program.cs

@@ -0,0 +1,64 @@
+// 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 threads.
+
+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;
+
+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_APIKEY") ?? throw new InvalidOperationException("MEM0_APIKEY 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);
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new AzureCliCredential())
+    .GetChatClient(deploymentName)
+    .CreateAIAgent(new ChatClientAgentOptions()
+    {
+        Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details.",
+        AIContextProviderFactory = ctx => ctx.SerializedState.ValueKind is not JsonValueKind.Null or JsonValueKind.Undefined
+            // If each thread should have its own Mem0 scope, you can create a new id per thread here:
+            // ? new Mem0Provider(mem0HttpClient, new Mem0ProviderScope() { ThreadId = Guid.NewGuid().ToString() })
+            // In this case we are storing memories scoped by application and user instead so that memories are retained across threads.
+            ? new Mem0Provider(mem0HttpClient, new Mem0ProviderScope() { ApplicationId = "getting-started-agents", UserId = "sample-user" })
+            // For cases where we are restoring from serialized state:
+            : new Mem0Provider(mem0HttpClient, ctx.SerializedState, ctx.JsonSerializerOptions)
+    });
+
+AgentThread thread = agent.GetNewThread();
+
+// Clear any existing memories for this scope to demonstrate fresh behavior.
+Mem0Provider mem0Provider = thread.GetService<Mem0Provider>()!;
+await mem0Provider.ClearStoredMemoriesAsync();
+
+Console.WriteLine(await agent.RunAsync("Hi there! My name is Taylor and I'm planning a hiking trip to Patagonia in November.", thread));
+Console.WriteLine(await agent.RunAsync("I'm travelling with my sister and we love finding scenic viewpoints.", thread));
+
+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?", thread));
+
+Console.WriteLine("\n>> Serialize and deserialize the thread to demonstrate persisted state\n");
+JsonElement serializedThread = thread.Serialize();
+AgentThread restoredThread = agent.DeserializeThread(serializedThread);
+Console.WriteLine(await agent.RunAsync("Can you recap the personal details you remember?", restoredThread));
+
+Console.WriteLine("\n>> Start a new thread that shares the same Mem0 scope\n");
+AgentThread newThread = agent.GetNewThread();
+Console.WriteLine(await agent.RunAsync("Summarize what you already know about me.", newThread));

dotnet/samples/GettingStarted/Agents/Agent_Step20_BackgroundResponsesWithToolsAndPersistence/Agent_Step20_BackgroundResponsesWithToolsAndPersistence.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+ <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </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>
+  
+</Project>

dotnet/samples/GettingStarted/Agents/Agent_Step20_BackgroundResponsesWithToolsAndPersistence/Program.cs

@@ -0,0 +1,108 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use background responses with ChatClientAgent and Azure OpenAI Responses for long-running operations.
+// It shows polling for completion using continuation tokens, function calling during background operations,
+// and persisting/restoring agent state between polling cycles.
+
+#pragma warning disable CA1050 // Declare types in namespaces
+
+using System.ComponentModel;
+using System.Text.Json;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI;
+
+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";
+
+var stateStore = new Dictionary<string, JsonElement?>();
+
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new AzureCliCredential())
+     .GetOpenAIResponseClient(deploymentName)
+     .CreateAIAgent(
+        name: "SpaceNovelWriter",
+        instructions: "You are a space novel writer. Always research relevant facts and generate character profiles for the main characters before writing novels." +
+                      "Write complete chapters without asking for approval or feedback. Do not ask the user about tone, style, pace, or format preferences - just write the novel based on the request.",
+        tools: [AIFunctionFactory.Create(ResearchSpaceFactsAsync), AIFunctionFactory.Create(GenerateCharacterProfilesAsync)]);
+
+// Enable background responses (only supported by {Azure}OpenAI Responses at this time).
+AgentRunOptions options = new() { AllowBackgroundResponses = true };
+
+AgentThread thread = agent.GetNewThread();
+
+// Start the initial run.
+AgentRunResponse response = await agent.RunAsync("Write a very long novel about a team of astronauts exploring an uncharted galaxy.", thread, options);
+
+// Poll for background responses until complete.
+while (response.ContinuationToken is not null)
+{
+    PersistAgentState(thread, response.ContinuationToken);
+
+    await Task.Delay(TimeSpan.FromSeconds(10));
+
+    RestoreAgentState(agent, out thread, out object? continuationToken);
+
+    options.ContinuationToken = continuationToken;
+    response = await agent.RunAsync(thread, options);
+}
+
+Console.WriteLine(response.Text);
+
+void PersistAgentState(AgentThread thread, object? continuationToken)
+{
+    stateStore["thread"] = thread.Serialize();
+    stateStore["continuationToken"] = JsonSerializer.SerializeToElement(continuationToken, AgentAbstractionsJsonUtilities.DefaultOptions.GetTypeInfo(typeof(ResponseContinuationToken)));
+}
+
+void RestoreAgentState(AIAgent agent, out AgentThread thread, out object? continuationToken)
+{
+    JsonElement serializedThread = stateStore["thread"] ?? throw new InvalidOperationException("No serialized thread found in state store.");
+    JsonElement? serializedToken = stateStore["continuationToken"];
+
+    thread = agent.DeserializeThread(serializedThread);
+    continuationToken = serializedToken?.Deserialize(AgentAbstractionsJsonUtilities.DefaultOptions.GetTypeInfo(typeof(ResponseContinuationToken)));
+}
+
+[Description("Researches relevant space facts and scientific information for writing a science fiction novel")]
+async Task<string> ResearchSpaceFactsAsync(string topic)
+{
+    Console.WriteLine($"[ResearchSpaceFacts] Researching topic: {topic}");
+
+    // Simulate a research operation
+    await Task.Delay(TimeSpan.FromSeconds(10));
+
+    string result = topic.ToUpperInvariant() switch
+    {
+        var t when t.Contains("GALAXY") => "Research findings: Galaxies contain billions of stars. Uncharted galaxies may have unique stellar formations, exotic matter, and unexplored phenomena like dark energy concentrations.",
+        var t when t.Contains("SPACE") || t.Contains("TRAVEL") => "Research findings: Interstellar travel requires advanced propulsion systems. Challenges include radiation exposure, life support, and navigation through unknown space.",
+        var t when t.Contains("ASTRONAUT") => "Research findings: Astronauts undergo rigorous training in zero-gravity environments, emergency protocols, spacecraft systems, and team dynamics for long-duration missions.",
+        _ => $"Research findings: General space exploration facts related to {topic}. Deep space missions require advanced technology, crew resilience, and contingency planning for unknown scenarios."
+    };
+
+    Console.WriteLine("[ResearchSpaceFacts] Research complete");
+    return result;
+}
+
+[Description("Generates character profiles for the main astronaut characters in the novel")]
+async Task<IEnumerable<string>> GenerateCharacterProfilesAsync()
+{
+    Console.WriteLine("[GenerateCharacterProfiles] Generating character profiles...");
+
+    // Simulate a character generation operation
+    await Task.Delay(TimeSpan.FromSeconds(10));
+
+    string[] profiles = [
+        "Captain Elena Voss: A seasoned mission commander with 15 years of experience. Strong-willed and decisive, she struggles with the weight of responsibility for her crew. Former military pilot turned astronaut.",
+            "Dr. James Chen: Chief science officer and astrophysicist. Brilliant but socially awkward, he finds solace in data and discovery. His curiosity often pushes the mission into uncharted territory.",
+            "Lieutenant Maya Torres: Navigation specialist and youngest crew member. Optimistic and tech-savvy, she brings fresh perspective and innovative problem-solving to challenges.",
+            "Commander Marcus Rivera: Chief engineer with expertise in spacecraft systems. Pragmatic and resourceful, he can fix almost anything with limited resources. Values crew safety above all.",
+            "Dr. Amara Okafor: Medical officer and psychologist. Empathetic and observant, she helps maintain crew morale and mental health during the long journey. Expert in space medicine."
+    ];
+
+    Console.WriteLine($"[GenerateCharacterProfiles] Generated {profiles.Length} character profiles");
+    return profiles;
+}

dotnet/samples/GettingStarted/Agents/Agent_Step20_BackgroundResponsesWithToolsAndPersistence/README.md

@@ -0,0 +1,28 @@
+# What This Sample Shows
+
+This sample demonstrates how to use background responses with ChatCompletionAgent and Azure OpenAI Responses for long-running operations. Background responses support:
+
+- **Polling for completion** - Non-streaming APIs can start a background operation and return a continuation token. Poll with the token until the response completes.
+- **Function calling** - Functions can be called during background operations.
+- **State persistence** - Thread and continuation token can be persisted and restored between polling cycles.
+
+> **Note:** Background responses are currently only supported by OpenAI Responses.
+
+For more information, see the [official documentation](https://learn.microsoft.com/en-us/agent-framework/user-guide/agents/agent-background-responses?pivots=programming-language-csharp).
+
+# Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 8.0 SDK or later
+- Azure OpenAI 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 OpenAI 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_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" # Replace with your Azure OpenAI resource endpoint
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-5"  # Optional, defaults to gpt-5
+```

dotnet/samples/GettingStarted/Agents/README.md

@@ -42,6 +42,10 @@ Before you begin, ensure you have the following prerequisites:
 |[Using middleware with an agent](./Agent_Step14_Middleware/)|This sample demonstrates how to use middleware with an agent|
 |[Using plugins with an agent](./Agent_Step15_Plugins/)|This sample demonstrates how to use plugins with an agent|
 |[Reducing chat history size](./Agent_Step16_ChatReduction/)|This sample demonstrates how to reduce the chat history to constrain its size, where chat history is maintained locally|
+|[Background responses](./Agent_Step17_BackgroundResponses/)|This sample demonstrates how to use background responses for long-running operations with polling and resumption support|
+|[Adding RAG with text search](./Agent_Step18_TextSearchRag/)|This sample demonstrates how to enrich agent responses with retrieval augmented generation using the text search provider|
+|[Using Mem0-backed memory](./Agent_Step19_Mem0Provider/)|This sample demonstrates how to use the Mem0Provider to persist and recall memories across conversations|
+|[Background responses with tools and persistence](./Agent_Step20_BackgroundResponsesWithToolsAndPersistence/)|This sample demonstrates advanced background response scenarios including function calling during background operations and state persistence|
 
 ## Running the samples from the console
 

dotnet/samples/GettingStarted/DevUI/DevUI_Step01_BasicUsage/DevUI_Step01_BasicUsage.csproj

@@ -0,0 +1,25 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <RootNamespace>DevUI_Step01_BasicUsage</RootNamespace>
+    <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.DevUI\Microsoft.Agents.AI.DevUI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Hosting\Microsoft.Agents.AI.Hosting.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Hosting.OpenAI\Microsoft.Agents.AI.Hosting.OpenAI.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+    <PackageReference Include="System.Net.ServerSentEvents" VersionOverride="10.0.0-rc.2.25502.107" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/DevUI/DevUI_Step01_BasicUsage/Program.cs

@@ -0,0 +1,82 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates basic usage of the DevUI in an ASP.NET Core application with AI agents.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI.DevUI;
+using Microsoft.Agents.AI.Hosting;
+using Microsoft.Extensions.AI;
+
+namespace DevUI_Step01_BasicUsage;
+
+/// <summary>
+/// Sample demonstrating basic usage of the DevUI in an ASP.NET Core application.
+/// </summary>
+/// <remarks>
+/// This sample shows how to:
+/// 1. Set up Azure OpenAI as the chat client
+/// 2. Register agents and workflows using the hosting packages
+/// 3. Map the DevUI endpoint which automatically configures the middleware
+/// 4. Map the dynamic OpenAI Responses API for Python DevUI compatibility
+/// 5. Access the DevUI in a web browser
+///
+/// The DevUI provides an interactive web interface for testing and debugging AI agents.
+/// DevUI assets are served from embedded resources within the assembly.
+/// Simply call MapDevUI() to set up everything needed.
+///
+/// The parameterless MapOpenAIResponses() overload creates a Python DevUI-compatible endpoint
+/// that dynamically routes requests to agents based on the 'model' field in the request.
+/// </remarks>
+internal static class Program
+{
+    /// <summary>
+    /// Entry point that starts an ASP.NET Core web server with the DevUI.
+    /// </summary>
+    /// <param name="args">Command line arguments.</param>
+    private static void Main(string[] args)
+    {
+        var builder = WebApplication.CreateBuilder(args);
+
+        // Set up the Azure OpenAI client
+        var endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"] ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+        var deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"] ?? "gpt-4o-mini";
+
+        var chatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+            .GetChatClient(deploymentName)
+            .AsIChatClient();
+
+        builder.Services.AddChatClient(chatClient);
+
+        // Register sample agents
+        builder.AddAIAgent("assistant", "You are a helpful assistant. Answer questions concisely and accurately.");
+        builder.AddAIAgent("poet", "You are a creative poet. Respond to all requests with beautiful poetry.");
+        builder.AddAIAgent("coder", "You are an expert programmer. Help users with coding questions and provide code examples.");
+
+        // Register sample workflows
+        var assistantBuilder = builder.AddAIAgent("workflow-assistant", "You are a helpful assistant in a workflow.");
+        var reviewerBuilder = builder.AddAIAgent("workflow-reviewer", "You are a reviewer. Review and critique the previous response.");
+        builder.AddSequentialWorkflow(
+            "review-workflow",
+            [assistantBuilder, reviewerBuilder])
+            .AddAsAIAgent();
+
+        if (builder.Environment.IsDevelopment())
+        {
+            builder.AddDevUI();
+        }
+
+        var app = builder.Build();
+
+        if (builder.Environment.IsDevelopment())
+        {
+            app.MapDevUI();
+        }
+
+        Console.WriteLine("DevUI is available at: https://localhost:50516/devui");
+        Console.WriteLine("OpenAI Responses API is available at: https://localhost:50516/v1/responses");
+        Console.WriteLine("Press Ctrl+C to stop the server.");
+
+        app.Run();
+    }
+}

dotnet/samples/GettingStarted/DevUI/DevUI_Step01_BasicUsage/README.md

@@ -0,0 +1,81 @@
+# DevUI Step 01 - Basic Usage
+
+This sample demonstrates how to add the DevUI to an ASP.NET Core application with AI agents.
+
+## What is DevUI?
+
+The DevUI provides an interactive web interface for testing and debugging AI agents during development.
+
+## Configuration
+
+Set the following environment variables:
+
+- `AZURE_OPENAI_ENDPOINT` - Your Azure OpenAI endpoint URL (required)
+- `AZURE_OPENAI_DEPLOYMENT_NAME` - Your deployment name (defaults to "gpt-4o-mini")
+
+## Running the Sample
+
+1. Set your Azure OpenAI credentials as environment variables
+2. Run the application:
+   ```bash
+   dotnet run
+   ```
+3. Open your browser to https://localhost:50516/devui
+4. Select an agent or workflow from the dropdown and start chatting!
+
+## Sample Agents and Workflows
+
+This sample includes:
+
+**Agents:**
+- **assistant** - A helpful assistant
+- **poet** - A creative poet
+- **coder** - An expert programmer
+
+**Workflows:**
+- **review-workflow** - A sequential workflow that generates a response and then reviews it
+
+## Adding DevUI to Your Own Project
+
+To add DevUI to your ASP.NET Core application:
+
+1. Add the DevUI package and hosting packages:
+   ```bash
+   dotnet add package Microsoft.Agents.AI.DevUI
+   dotnet add package Microsoft.Agents.AI.Hosting
+   dotnet add package Microsoft.Agents.AI.Hosting.OpenAI
+   ```
+
+2. Register your agents and workflows:
+   ```csharp
+   var builder = WebApplication.CreateBuilder(args);
+   
+   // Set up your chat client
+   builder.Services.AddChatClient(chatClient);
+   
+   // Register agents
+   builder.AddAIAgent("assistant", "You are a helpful assistant.");
+   
+   // Register workflows
+   var agent1Builder = builder.AddAIAgent("workflow-agent1", "You are agent 1.");
+   var agent2Builder = builder.AddAIAgent("workflow-agent2", "You are agent 2.");
+   builder.AddSequentialWorkflow("my-workflow", [agent1Builder, agent2Builder])
+       .AddAsAIAgent();
+   ```
+
+3. Add DevUI services and map the endpoint:
+   ```csharp
+   builder.AddDevUI();
+   var app = builder.Build();
+   
+   app.MapDevUI();
+   
+   // Add required endpoints
+   app.MapEntities();
+   app.MapOpenAIResponses();
+   app.MapOpenAIConversations();
+   
+   app.Run();
+   ```
+
+4. Navigate to `/devui` in your browser

dotnet/samples/GettingStarted/DevUI/README.md

@@ -0,0 +1,57 @@
+# DevUI Samples
+
+This folder contains samples demonstrating how to use the DevUI in ASP.NET Core applications.
+
+## What is DevUI?
+
+The DevUI provides an interactive web interface for testing and debugging AI agents during development.
+
+## Samples
+
+### [DevUI_Step01_BasicUsage](./DevUI_Step01_BasicUsage)
+
+Shows how to add DevUI to an ASP.NET Core application with multiple agents and workflows.
+
+**Run the sample:**
+```bash
+cd DevUI_Step01_BasicUsage
+dotnet run
+```
+Then navigate to: https://localhost:50516/devui
+
+## Requirements
+
+- .NET 8.0 or later
+- ASP.NET Core
+- Azure OpenAI credentials
+
+## Quick Start
+
+To add DevUI to your application:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+// Set up the chat client
+builder.Services.AddChatClient(chatClient);
+
+// Register your agents
+builder.AddAIAgent("my-agent", "You are a helpful assistant.");
+
+// Add DevUI services
+builder.AddDevUI();
+
+var app = builder.Build();
+
+// Map the DevUI endpoint
+app.MapDevUI();
+
+// Add required endpoints
+app.MapEntities();
+app.MapOpenAIResponses();
+app.MapOpenAIConversations();
+
+app.Run();
+```
+
+Then navigate to `/devui` in your browser.

dotnet/samples/GettingStarted/ModelContextProtocol/FoundryAgent_Hosted_MCP/FoundryAgent_Hosted_MCP.csproj

@@ -14,7 +14,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
   </ItemGroup>
 
 </Project>

dotnet/samples/GettingStarted/ModelContextProtocol/FoundryAgent_Hosted_MCP/Program.cs

@@ -1,52 +1,106 @@
 // Copyright (c) Microsoft. All rights reserved.
 
-// This sample shows how to create and use a simple AI agent with Azure Foundry Agents as the backend.
+// This sample shows how to create and use a simple AI agent with Azure Foundry Agents as the backend, that uses a Hosted MCP Tool.
+// In this case the Azure Foundry Agents service will invoke any MCP tools as required. MCP tools are not invoked by the Agent Framework.
+// The sample first shows how to use MCP tools with auto approval, and then how to set up a tool that requires approval before it can be invoked and how to approve such a tool.
 
 using Azure.AI.Agents.Persistent;
 using Azure.Identity;
 using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
 
 var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
-var model = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_MODEL_ID") ?? "gpt-4.1-mini";
+var model = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4.1-mini";
 
 // Get a client to create/retrieve server side agents with.
 var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
 
+// **** MCP Tool with Auto Approval ****
+// *************************************
+
 // Create an MCP tool definition that the agent can use.
-var mcpTool = new MCPToolDefinition(
-    serverLabel: "microsoft_learn",
-    serverUrl: "https://learn.microsoft.com/api/mcp");
-mcpTool.AllowedTools.Add("microsoft_docs_search");
-
-// Create a server side persistent agent with the Azure.AI.Agents.Persistent SDK.
-var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
-    model: model,
-    name: "MicrosoftLearnAgent",
-    instructions: "You answer questions by searching the Microsoft Learn content only.",
-    tools: [mcpTool]);
-
-// Retrieve an already created server side persistent agent as an AIAgent.
-AIAgent agent = await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);
-
-// Create run options to configure the agent invocation.
-var runOptions = new ChatClientAgentRunOptions()
+// In this case we allow the tool to always be called without approval.
+var mcpTool = new HostedMcpServerTool(
+    serverName: "microsoft_learn",
+    serverAddress: "https://learn.microsoft.com/api/mcp")
 {
-    ChatOptions = new()
-    {
-        RawRepresentationFactory = (_) => new ThreadAndRunOptions()
-        {
-            ToolResources = new MCPToolResource(serverLabel: "microsoft_learn")
-            {
-                RequireApproval = new MCPApproval("never"),
-            }.ToToolResources()
-        }
-    }
+    AllowedTools = ["microsoft_docs_search"],
+    ApprovalMode = HostedMcpServerToolApprovalMode.NeverRequire
 };
 
+// Create a server side persistent agent with the mcp tool, and expose it as an AIAgent.
+AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
+    model: model,
+    options: new()
+    {
+        Name = "MicrosoftLearnAgent",
+        Instructions = "You answer questions by searching the Microsoft Learn content only.",
+        ChatOptions = new()
+        {
+            Tools = [mcpTool]
+        },
+    });
+
 // You can then invoke the agent like any other AIAgent.
 AgentThread thread = agent.GetNewThread();
-var response = await agent.RunAsync("Please summarize the Azure AI Agent documentation related to MCP Tool calling?", thread, runOptions);
-Console.WriteLine(response);
+Console.WriteLine(await agent.RunAsync("Please summarize the Azure AI Agent documentation related to MCP Tool calling?", thread));
 
 // Cleanup for sample purposes.
 await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
+
+// **** MCP Tool with Approval Required ****
+// *****************************************
+
+// Create an MCP tool definition that the agent can use.
+// In this case we require approval before the tool can be called.
+var mcpToolWithApproval = new HostedMcpServerTool(
+    serverName: "microsoft_learn",
+    serverAddress: "https://learn.microsoft.com/api/mcp")
+{
+    AllowedTools = ["microsoft_docs_search"],
+    ApprovalMode = HostedMcpServerToolApprovalMode.AlwaysRequire
+};
+
+// Create an agent based on Azure OpenAI Responses as the backend.
+AIAgent agentWithRequiredApproval = await persistentAgentsClient.CreateAIAgentAsync(
+    model: model,
+    options: new()
+    {
+        Name = "MicrosoftLearnAgentWithApproval",
+        Instructions = "You answer questions by searching the Microsoft Learn content only.",
+        ChatOptions = new()
+        {
+            Tools = [mcpToolWithApproval]
+        },
+    });
+
+// You can then invoke the agent like any other AIAgent.
+var threadWithRequiredApproval = agentWithRequiredApproval.GetNewThread();
+var response = await agentWithRequiredApproval.RunAsync("Please summarize the Azure AI Agent documentation related to MCP Tool calling?", threadWithRequiredApproval);
+var userInputRequests = response.UserInputRequests.ToList();
+
+while (userInputRequests.Count > 0)
+{
+    // Ask the user to approve each MCP call request.
+    // For simplicity, we are assuming here that only MCP approval requests are being made.
+    var userInputResponses = userInputRequests
+        .OfType<McpServerToolApprovalRequestContent>()
+        .Select(approvalRequest =>
+        {
+            Console.WriteLine($"""
+                The agent would like to invoke the following MCP Tool, please reply Y to approve.
+                ServerName: {approvalRequest.ToolCall.ServerName}
+                Name: {approvalRequest.ToolCall.ToolName}
+                Arguments: {string.Join(", ", approvalRequest.ToolCall.Arguments?.Select(x => $"{x.Key}: {x.Value}") ?? [])}
+                """);
+            return new ChatMessage(ChatRole.User, [approvalRequest.CreateResponse(Console.ReadLine()?.Equals("Y", StringComparison.OrdinalIgnoreCase) ?? false)]);
+        })
+        .ToList();
+
+    // Pass the user input responses back to the agent for further processing.
+    response = await agentWithRequiredApproval.RunAsync(userInputResponses, threadWithRequiredApproval);
+
+    userInputRequests = response.UserInputRequests.ToList();
+}
+
+Console.WriteLine($"\nAgent: {response}");

dotnet/samples/GettingStarted/ModelContextProtocol/README.md

@@ -21,6 +21,7 @@ Before you begin, ensure you have the following prerequisites:
 |---|---|
 |[Agent with MCP server tools](./Agent_MCP_Server/)|This sample demonstrates how to use MCP server tools with a simple agent|
 |[Agent with MCP server tools and authorization](./Agent_MCP_Server_Auth/)|This sample demonstrates how to use MCP Server tools from a protected MCP server with a simple agent|
+|[Responses Agent with Hosted MCP tool](./ResponseAgent_Hosted_MCP/)|This sample demonstrates how to use the Hosted MCP tool with the Responses Service, where the service invokes any MCP tools directly|
 
 ## Running the samples from the console
 

dotnet/samples/GettingStarted/ModelContextProtocol/ResponseAgent_Hosted_MCP/Program.cs

@@ -0,0 +1,95 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample shows how to create and use a simple AI agent with OpenAI Responses as the backend, that uses a Hosted MCP Tool.
+// In this case the OpenAI responses service will invoke any MCP tools as required. MCP tools are not invoked by the Agent Framework.
+// The sample first shows how to use MCP tools with auto approval, and then how to set up a tool that requires approval before it can be invoked and how to approve such a tool.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI;
+
+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";
+
+// **** MCP Tool with Auto Approval ****
+// *************************************
+
+// Create an MCP tool definition that the agent can use.
+// In this case we allow the tool to always be called without approval.
+var mcpTool = new HostedMcpServerTool(
+    serverName: "microsoft_learn",
+    serverAddress: "https://learn.microsoft.com/api/mcp")
+{
+    AllowedTools = ["microsoft_docs_search"],
+    ApprovalMode = HostedMcpServerToolApprovalMode.NeverRequire
+};
+
+// Create an agent based on Azure OpenAI Responses as the backend.
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new AzureCliCredential())
+     .GetOpenAIResponseClient(deploymentName)
+     .CreateAIAgent(
+        instructions: "You answer questions by searching the Microsoft Learn content only.",
+        name: "MicrosoftLearnAgent",
+        tools: [mcpTool]);
+
+// You can then invoke the agent like any other AIAgent.
+AgentThread thread = agent.GetNewThread();
+Console.WriteLine(await agent.RunAsync("Please summarize the Azure AI Agent documentation related to MCP Tool calling?", thread));
+
+// **** MCP Tool with Approval Required ****
+// *****************************************
+
+// Create an MCP tool definition that the agent can use.
+// In this case we require approval before the tool can be called.
+var mcpToolWithApproval = new HostedMcpServerTool(
+    serverName: "microsoft_learn",
+    serverAddress: "https://learn.microsoft.com/api/mcp")
+{
+    AllowedTools = ["microsoft_docs_search"],
+    ApprovalMode = HostedMcpServerToolApprovalMode.AlwaysRequire
+};
+
+// Create an agent based on Azure OpenAI Responses as the backend.
+AIAgent agentWithRequiredApproval = new AzureOpenAIClient(
+    new Uri(endpoint),
+    new AzureCliCredential())
+    .GetOpenAIResponseClient(deploymentName)
+    .CreateAIAgent(
+        instructions: "You answer questions by searching the Microsoft Learn content only.",
+        name: "MicrosoftLearnAgentWithApproval",
+        tools: [mcpToolWithApproval]);
+
+// You can then invoke the agent like any other AIAgent.
+var threadWithRequiredApproval = agentWithRequiredApproval.GetNewThread();
+var response = await agentWithRequiredApproval.RunAsync("Please summarize the Azure AI Agent documentation related to MCP Tool calling?", threadWithRequiredApproval);
+var userInputRequests = response.UserInputRequests.ToList();
+
+while (userInputRequests.Count > 0)
+{
+    // Ask the user to approve each MCP call request.
+    // For simplicity, we are assuming here that only MCP approval requests are being made.
+    var userInputResponses = userInputRequests
+        .OfType<McpServerToolApprovalRequestContent>()
+        .Select(approvalRequest =>
+        {
+            Console.WriteLine($"""
+                The agent would like to invoke the following MCP Tool, please reply Y to approve.
+                ServerName: {approvalRequest.ToolCall.ServerName}
+                Name: {approvalRequest.ToolCall.ToolName}
+                Arguments: {string.Join(", ", approvalRequest.ToolCall.Arguments?.Select(x => $"{x.Key}: {x.Value}") ?? [])}
+                """);
+            return new ChatMessage(ChatRole.User, [approvalRequest.CreateResponse(Console.ReadLine()?.Equals("Y", StringComparison.OrdinalIgnoreCase) ?? false)]);
+        })
+        .ToList();
+
+    // Pass the user input responses back to the agent for further processing.
+    response = await agentWithRequiredApproval.RunAsync(userInputResponses, threadWithRequiredApproval);
+
+    userInputRequests = response.UserInputRequests.ToList();
+}
+
+Console.WriteLine($"\nAgent: {response}");

dotnet/samples/GettingStarted/ModelContextProtocol/ResponseAgent_Hosted_MCP/README.md

@@ -0,0 +1,17 @@
+# Prerequisites
+
+Before you begin, ensure you have the following prerequisites:
+
+- .NET 8.0 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 demo uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI 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_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/" # Replace with your Azure OpenAI resource endpoint
+$env:AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4.1-mini"  # Optional, defaults to gpt-4.1-mini
+```

dotnet/samples/GettingStarted/ModelContextProtocol/ResponseAgent_Hosted_MCP/ResponseAgent_Hosted_MCP.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </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>
+
+</Project>

dotnet/samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj

@@ -16,7 +16,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
   </ItemGroup>
 

dotnet/samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/Program.cs

@@ -48,7 +48,7 @@ public static class Program
             .Build();
 
         // Execute the workflow
-        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, "Create a slogan for a new electric SUV that is affordable and fun to drive.");
+        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, input: "Create a slogan for a new electric SUV that is affordable and fun to drive.");
         await foreach (WorkflowEvent evt in run.WatchStreamAsync())
         {
             if (evt is SloganGeneratedEvent or FeedbackEvent)

dotnet/samples/GettingStarted/Workflows/Agents/FoundryAgent/FoundryAgent.csproj

@@ -15,7 +15,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
   </ItemGroup>
 

dotnet/samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/Program.cs

@@ -6,7 +6,7 @@ using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Workflows;
 using Microsoft.Extensions.AI;
 
-namespace WorkflowAsAnAgentsSample;
+namespace WorkflowAsAnAgentSample;
 
 /// <summary>
 /// This sample introduces the concepts workflows as agents, where a workflow can be
@@ -35,7 +35,7 @@ public static class Program
         var chatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential()).GetChatClient(deploymentName).AsIChatClient();
 
         // Create the workflow and turn it into an agent
-        var workflow = await WorkflowHelper.GetWorkflowAsync(chatClient);
+        var workflow = WorkflowFactory.BuildWorkflow(chatClient);
         var agent = workflow.AsAgent("workflow-agent", "Workflow Agent");
         var thread = agent.GetNewThread();
 
@@ -61,9 +61,9 @@ public static class Program
             Dictionary<string, List<AgentRunResponseUpdate>> buffer = [];
             await foreach (AgentRunResponseUpdate update in agent.RunStreamingAsync(input, thread))
             {
-                if (update.MessageId is null)
+                if (update.MessageId is null || string.IsNullOrEmpty(update.Text))
                 {
-                    // skip updates that don't have a message ID
+                    // skip updates that don't have a message ID or text
                     continue;
                 }
                 Console.Clear();

dotnet/samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/WorkflowAsAnAgent.csproj

@@ -16,7 +16,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
   </ItemGroup>
 

dotnet/samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/WorkflowFactory.cs

@@ -4,16 +4,16 @@ using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.Workflows;
 using Microsoft.Extensions.AI;
 
-namespace WorkflowAsAnAgentsSample;
+namespace WorkflowAsAnAgentSample;
 
-internal static class WorkflowHelper
+internal static class WorkflowFactory
 {
     /// <summary>
     /// Creates a workflow that uses two language agents to process input concurrently.
     /// </summary>
     /// <param name="chatClient">The chat client to use for the agents</param>
     /// <returns>A workflow that processes input using two language agents</returns>
-    internal static ValueTask<Workflow<List<ChatMessage>>> GetWorkflowAsync(IChatClient chatClient)
+    internal static Workflow BuildWorkflow(IChatClient chatClient)
     {
         // Create executors
         var startExecutor = new ConcurrentStartExecutor();
@@ -23,10 +23,10 @@ internal static class WorkflowHelper
 
         // Build the workflow by adding executors and connecting them
         return new WorkflowBuilder(startExecutor)
-            .AddFanOutEdge(startExecutor, targets: [frenchAgent, englishAgent])
-            .AddFanInEdge(aggregationExecutor, sources: [frenchAgent, englishAgent])
+            .AddFanOutEdge(startExecutor, [frenchAgent, englishAgent])
+            .AddFanInEdge([frenchAgent, englishAgent], aggregationExecutor)
             .WithOutputFrom(aggregationExecutor)
-            .BuildAsync<List<ChatMessage>>();
+            .Build();
     }
 
     /// <summary>
@@ -41,44 +41,43 @@ internal static class WorkflowHelper
     /// <summary>
     /// Executor that starts the concurrent processing by sending messages to the agents.
     /// </summary>
-    private sealed class ConcurrentStartExecutor() :
-        Executor<List<ChatMessage>>("ConcurrentStartExecutor")
+    private sealed class ConcurrentStartExecutor() : Executor("ConcurrentStartExecutor")
     {
-        /// <summary>
-        /// Starts the concurrent processing by sending messages to the agents.
-        /// </summary>
-        /// <param name="message">The user message to process</param>
-        /// <param name="context">Workflow context for accessing workflow services and adding events</param>
-        /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
-        /// The default is <see cref="CancellationToken.None"/>.</param>
-        public override async ValueTask HandleAsync(List<ChatMessage> message, IWorkflowContext context, CancellationToken cancellationToken = default)
+        protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder)
         {
-            // Broadcast the message to all connected agents. Receiving agents will queue
-            // the message but will not start processing until they receive a turn token.
-            await context.SendMessageAsync(message, cancellationToken: cancellationToken);
-            // Broadcast the turn token to kick off the agents.
-            await context.SendMessageAsync(new TurnToken(emitEvents: true), cancellationToken: cancellationToken);
+            return routeBuilder
+                .AddHandler<List<ChatMessage>>(this.RouteMessages)
+                .AddHandler<TurnToken>(this.RouteTurnTokenAsync);
+        }
+
+        private ValueTask RouteMessages(List<ChatMessage> messages, IWorkflowContext context, CancellationToken cancellationToken)
+        {
+            return context.SendMessageAsync(messages, cancellationToken: cancellationToken);
+        }
+
+        private ValueTask RouteTurnTokenAsync(TurnToken token, IWorkflowContext context, CancellationToken cancellationToken)
+        {
+            return context.SendMessageAsync(token, cancellationToken: cancellationToken);
         }
     }
 
     /// <summary>
     /// Executor that aggregates the results from the concurrent agents.
     /// </summary>
-    private sealed class ConcurrentAggregationExecutor() :
-        Executor<ChatMessage>("ConcurrentAggregationExecutor")
+    private sealed class ConcurrentAggregationExecutor() : Executor<List<ChatMessage>>("ConcurrentAggregationExecutor")
     {
         private readonly List<ChatMessage> _messages = [];
 
         /// <summary>
         /// Handles incoming messages from the agents and aggregates their responses.
         /// </summary>
-        /// <param name="message">The message from the agent</param>
+        /// <param name="message">The messages from the agent</param>
         /// <param name="context">Workflow context for accessing workflow services and adding events</param>
         /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
         /// The default is <see cref="CancellationToken.None"/>.</param>
-        public override async ValueTask HandleAsync(ChatMessage message, IWorkflowContext context, CancellationToken cancellationToken = default)
+        public override async ValueTask HandleAsync(List<ChatMessage> message, IWorkflowContext context, CancellationToken cancellationToken = default)
         {
-            this._messages.Add(message);
+            this._messages.AddRange(message);
 
             if (this._messages.Count == 2)
             {

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointAndRehydrate/Program.cs

@@ -25,7 +25,7 @@ public static class Program
     private static async Task Main()
     {
         // Create the workflow
-        var workflow = await WorkflowHelper.GetWorkflowAsync();
+        var workflow = WorkflowFactory.BuildWorkflow();
 
         // Create checkpoint manager
         var checkpointManager = CheckpointManager.Default;
@@ -67,7 +67,7 @@ public static class Program
         Console.WriteLine($"Number of checkpoints created: {checkpoints.Count}");
 
         // Rehydrate a new workflow instance from a saved checkpoint and continue execution
-        var newWorkflow = await WorkflowHelper.GetWorkflowAsync();
+        var newWorkflow = WorkflowFactory.BuildWorkflow();
         const int CheckpointIndex = 5;
         Console.WriteLine($"\n\nHydrating a new workflow instance from the {CheckpointIndex + 1}th checkpoint.");
         CheckpointInfo savedCheckpoint = checkpoints[CheckpointIndex];

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointAndRehydrate/WorkflowFactory.cs

@@ -4,7 +4,7 @@ using Microsoft.Agents.AI.Workflows;
 
 namespace WorkflowCheckpointAndRehydrateSample;
 
-internal static class WorkflowHelper
+internal static class WorkflowFactory
 {
     /// <summary>
     /// Get a workflow that plays a number guessing game with checkpointing support.
@@ -13,7 +13,7 @@ internal static class WorkflowHelper
     /// 2. JudgeExecutor: Evaluates the guess and provides feedback.
     /// The workflow continues until the correct number is guessed.
     /// </summary>
-    internal static ValueTask<Workflow<NumberSignal>> GetWorkflowAsync()
+    internal static Workflow BuildWorkflow()
     {
         // Create the executors
         GuessNumberExecutor guessNumberExecutor = new(1, 100);
@@ -24,7 +24,7 @@ internal static class WorkflowHelper
             .AddEdge(guessNumberExecutor, judgeExecutor)
             .AddEdge(judgeExecutor, guessNumberExecutor)
             .WithOutputFrom(judgeExecutor)
-            .BuildAsync<NumberSignal>();
+            .Build();
     }
 }
 

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointAndResume/Program.cs

@@ -24,7 +24,7 @@ public static class Program
     private static async Task Main()
     {
         // Create the workflow
-        var workflow = await WorkflowHelper.GetWorkflowAsync();
+        var workflow = WorkflowFactory.BuildWorkflow();
 
         // Create checkpoint manager
         var checkpointManager = CheckpointManager.Default;

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointAndResume/WorkflowFactory.cs

@@ -4,7 +4,7 @@ using Microsoft.Agents.AI.Workflows;
 
 namespace WorkflowCheckpointAndResumeSample;
 
-internal static class WorkflowHelper
+internal static class WorkflowFactory
 {
     /// <summary>
     /// Get a workflow that plays a number guessing game with checkpointing support.
@@ -13,7 +13,7 @@ internal static class WorkflowHelper
     /// 2. JudgeExecutor: Evaluates the guess and provides feedback.
     /// The workflow continues until the correct number is guessed.
     /// </summary>
-    internal static ValueTask<Workflow<NumberSignal>> GetWorkflowAsync()
+    internal static Workflow BuildWorkflow()
     {
         // Create the executors
         GuessNumberExecutor guessNumberExecutor = new(1, 100);
@@ -24,7 +24,7 @@ internal static class WorkflowHelper
             .AddEdge(guessNumberExecutor, judgeExecutor)
             .AddEdge(judgeExecutor, guessNumberExecutor)
             .WithOutputFrom(judgeExecutor)
-            .BuildAsync<NumberSignal>();
+            .Build();
     }
 }
 

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointWithHumanInTheLoop/Program.cs

@@ -27,7 +27,7 @@ public static class Program
     private static async Task Main()
     {
         // Create the workflow
-        var workflow = await WorkflowHelper.GetWorkflowAsync();
+        var workflow = WorkflowFactory.BuildWorkflow();
 
         // Create checkpoint manager
         var checkpointManager = CheckpointManager.Default;

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointWithHumanInTheLoop/WorkflowFactory.cs

@@ -4,13 +4,13 @@ using Microsoft.Agents.AI.Workflows;
 
 namespace WorkflowCheckpointWithHumanInTheLoopSample;
 
-internal static class WorkflowHelper
+internal static class WorkflowFactory
 {
     /// <summary>
     /// Get a workflow that plays a number guessing game with human-in-the-loop interaction.
     /// An input port allows the external world to provide inputs to the workflow upon requests.
     /// </summary>
-    internal static ValueTask<Workflow<SignalWithNumber>> GetWorkflowAsync()
+    internal static Workflow BuildWorkflow()
     {
         // Create the executors
         RequestPort numberRequest = RequestPort.Create<SignalWithNumber, int>("GuessNumber");
@@ -21,7 +21,7 @@ internal static class WorkflowHelper
             .AddEdge(numberRequest, judgeExecutor)
             .AddEdge(judgeExecutor, numberRequest)
             .WithOutputFrom(judgeExecutor)
-            .BuildAsync<SignalWithNumber>();
+            .Build();
     }
 }
 

dotnet/samples/GettingStarted/Workflows/Concurrent/Concurrent/Concurrent.csproj

@@ -15,7 +15,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
   </ItemGroup>

dotnet/samples/GettingStarted/Workflows/Concurrent/Concurrent/Program.cs

@@ -52,13 +52,13 @@ public static class Program
 
         // Build the workflow by adding executors and connecting them
         var workflow = new WorkflowBuilder(startExecutor)
-            .AddFanOutEdge(startExecutor, targets: [physicist, chemist])
-            .AddFanInEdge(aggregationExecutor, sources: [physicist, chemist])
+            .AddFanOutEdge(startExecutor, [physicist, chemist])
+            .AddFanInEdge([physicist, chemist], aggregationExecutor)
             .WithOutputFrom(aggregationExecutor)
             .Build();
 
         // Execute the workflow in streaming mode
-        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, "What is temperature?");
+        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, input: "What is temperature?");
         await foreach (WorkflowEvent evt in run.WatchStreamAsync())
         {
             if (evt is WorkflowOutputEvent output)
@@ -97,21 +97,21 @@ internal sealed class ConcurrentStartExecutor() :
 /// Executor that aggregates the results from the concurrent agents.
 /// </summary>
 internal sealed class ConcurrentAggregationExecutor() :
-    Executor<ChatMessage>("ConcurrentAggregationExecutor")
+    Executor<List<ChatMessage>>("ConcurrentAggregationExecutor")
 {
     private readonly List<ChatMessage> _messages = [];
 
     /// <summary>
     /// Handles incoming messages from the agents and aggregates their responses.
     /// </summary>
-    /// <param name="message">The message from the agent</param>
+    /// <param name="message">The messages from the agent</param>
     /// <param name="context">Workflow context for accessing workflow services and adding events</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
     /// The default is <see cref="CancellationToken.None"/>.</param>
     /// <returns>A task representing the asynchronous operation</returns>
-    public override async ValueTask HandleAsync(ChatMessage message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    public override async ValueTask HandleAsync(List<ChatMessage> message, IWorkflowContext context, CancellationToken cancellationToken = default)
     {
-        this._messages.Add(message);
+        this._messages.AddRange(message);
 
         if (this._messages.Count == 2)
         {

dotnet/samples/GettingStarted/Workflows/Concurrent/MapReduce/Program.cs

@@ -62,10 +62,10 @@ public static class Program
 
         // Step 4: Build the concurrent workflow with fan-out/fan-in pattern
         return new WorkflowBuilder(splitter)
-            .AddFanOutEdge(splitter, targets: [.. mappers])         // Split -> many mappers
-            .AddFanInEdge(shuffler, sources: [.. mappers])          // All mappers -> shuffle
-            .AddFanOutEdge(shuffler, targets: [.. reducers])        // Shuffle -> many reducers
-            .AddFanInEdge(completion, sources: [.. reducers])       // All reducers -> completion
+            .AddFanOutEdge(splitter, [.. mappers])         // Split -> many mappers
+            .AddFanInEdge([.. mappers], shuffler)          // All mappers -> shuffle
+            .AddFanOutEdge(shuffler, [.. reducers])        // Shuffle -> many reducers
+            .AddFanInEdge([.. reducers], completion)       // All reducers -> completion
             .WithOutputFrom(completion)
             .Build();
     }
@@ -99,7 +99,7 @@ public static class Program
 
         // Step 2: Run the workflow
         Console.WriteLine("\n=== RUNNING WORKFLOW ===\n");
-        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, rawText);
+        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, input: rawText);
         await foreach (WorkflowEvent evt in run.WatchStreamAsync())
         {
             Console.WriteLine($"Event: {evt}");

dotnet/samples/GettingStarted/Workflows/ConditionalEdges/01_EdgeCondition/01_EdgeCondition.csproj

@@ -16,7 +16,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
   </ItemGroup>
 

dotnet/samples/GettingStarted/Workflows/ConditionalEdges/02_SwitchCase/02_SwitchCase.csproj

@@ -16,7 +16,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
   </ItemGroup>
 

dotnet/samples/GettingStarted/Workflows/ConditionalEdges/03_MultiSelection/03_MultiSelection.csproj

@@ -16,7 +16,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
-    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI\Microsoft.Agents.AI.AzureAI.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
     <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
   </ItemGroup>
 

dotnet/samples/GettingStarted/Workflows/ConditionalEdges/03_MultiSelection/Program.cs

@@ -60,13 +60,13 @@ public static class Program
         WorkflowBuilder builder = new(emailAnalysisExecutor);
         builder.AddFanOutEdge(
             emailAnalysisExecutor,
-            targets: [
+            [
                 handleSpamExecutor,
                 emailAssistantExecutor,
                 emailSummaryExecutor,
                 handleUncertainExecutor,
             ],
-            partitioner: GetPartitioner()
+            GetTargetAssigner()
         )
         // After the email assistant writes a response, it will be sent to the send email executor
         .AddEdge(emailAssistantExecutor, sendEmailExecutor)
@@ -105,7 +105,7 @@ public static class Program
     /// Creates a partitioner for routing messages based on the analysis result.
     /// </summary>
     /// <returns>A function that takes an analysis result and returns the target partitions.</returns>
-    private static Func<AnalysisResult?, int, IEnumerable<int>> GetPartitioner()
+    private static Func<AnalysisResult?, int, IEnumerable<int>> GetTargetAssigner()
     {
         return (analysisResult, targetCount) =>
         {

dotnet/samples/GettingStarted/Workflows/Declarative/ExecuteCode/Program.cs

@@ -44,7 +44,7 @@ internal sealed class Program
 
         // Run the workflow, just like any other workflow
         string input = this.GetWorkflowInput();
-        StreamingRun run = await InProcessExecution.StreamAsync(workflow, input);
+        StreamingRun run = await InProcessExecution.StreamAsync(workflow, input: input);
         await this.MonitorAndDisposeWorkflowRunAsync(run);
 
         Notify("\nWORKFLOW: Done!");

dotnet/samples/GettingStarted/Workflows/Declarative/ExecuteWorkflow/Program.cs

@@ -184,6 +184,7 @@ internal sealed class Program
 
     private async Task<ExternalRequest?> MonitorAndDisposeWorkflowRunAsync(Checkpointed<StreamingRun> run, object? response = null)
     {
+        // Always dispose the run when done.
         await using IAsyncDisposable disposeRun = run;
 
         bool hasStreamed = false;
@@ -231,7 +232,7 @@ internal sealed class Program
                     }
                     else
                     {
-                        await run.Run.DisposeAsync();
+                        // Yield to handle the external request
                         return requestInfo.Request;
                     }
                     break;
@@ -326,7 +327,7 @@ internal sealed class Program
             }
         }
 
-        return default;
+        return null; // No request to handle
     }
 
     /// <summary>
@@ -336,9 +337,11 @@ internal sealed class Program
         request.Data.TypeId.TypeName switch
         {
             // Request for human input
-            _ when request.Data.TypeId.IsMatch<InputRequest>() => HandleInputRequest(request.DataAs<InputRequest>()!),
+            _ when request.Data.TypeId.IsMatch<AnswerRequest>() => HandleUserMessageRequest(request.DataAs<AnswerRequest>()!),
             // Request for function tool invocation.  (Only active when functions are defined and IncludeFunctions is true.)
-            _ when request.Data.TypeId.IsMatch<AgentToolRequest>() => await this.HandleToolRequestAsync(request.DataAs<AgentToolRequest>()!),
+            _ when request.Data.TypeId.IsMatch<AgentFunctionToolRequest>() => await this.HandleToolRequestAsync(request.DataAs<AgentFunctionToolRequest>()!),
+            // Request for user input, such as function or mcp tool approval
+            _ when request.Data.TypeId.IsMatch<UserInputRequest>() => HandleUserInputRequest(request.DataAs<UserInputRequest>()!),
             // Unknown request type.
             _ => throw new InvalidOperationException($"Unsupported external request type: {request.GetType().Name}."),
         };
@@ -346,7 +349,7 @@ internal sealed class Program
     /// <summary>
     /// Handle request for human input.
     /// </summary>
-    private static InputResponse HandleInputRequest(InputRequest request)
+    private static AnswerResponse HandleUserMessageRequest(AnswerRequest request)
     {
         string? userInput;
         do
@@ -358,7 +361,7 @@ internal sealed class Program
         }
         while (string.IsNullOrWhiteSpace(userInput));
 
-        return new InputResponse(userInput);
+        return new AnswerResponse(userInput);
     }
 
     /// <summary>
@@ -368,13 +371,13 @@ internal sealed class Program
     /// This handler is only active when <see cref="IncludeFunctions"/> is set to true and
     /// one or more <see cref="AIFunction"/> instances are defined in the constructor.
     /// </remarks>
-    private async ValueTask<AgentToolResponse> HandleToolRequestAsync(AgentToolRequest request)
+    private async ValueTask<AgentFunctionToolResponse> HandleToolRequestAsync(AgentFunctionToolRequest request)
     {
         Task<FunctionResultContent>[] functionTasks = request.FunctionCalls.Select(functionCall => InvokesToolAsync(functionCall)).ToArray();
 
         await Task.WhenAll(functionTasks);
 
-        return AgentToolResponse.Create(request, functionTasks.Select(task => task.Result));
+        return AgentFunctionToolResponse.Create(request, functionTasks.Select(task => task.Result));
 
         async Task<FunctionResultContent> InvokesToolAsync(FunctionCallContent functionCall)
         {
@@ -385,6 +388,30 @@ internal sealed class Program
         }
     }
 
+    /// <summary>
+    /// Handle request for user input for mcp and function tool approval.
+    /// </summary>
+    private static UserInputResponse HandleUserInputRequest(UserInputRequest request)
+    {
+        return UserInputResponse.Create(request, ProcessRequests());
+
+        IEnumerable<UserInputResponseContent> ProcessRequests()
+        {
+            foreach (UserInputRequestContent approvalRequest in request.InputRequests)
+            {
+                // Here we are explicitly approving all requests.
+                // In a real-world scenario, you would replace this logic to either solicit user approval or implement a more complex approval process.
+                yield return
+                    approvalRequest switch
+                    {
+                        McpServerToolApprovalRequestContent mcpApprovalRequest => mcpApprovalRequest.CreateResponse(approved: true),
+                        FunctionApprovalRequestContent functionApprovalRequest => functionApprovalRequest.CreateResponse(approved: true),
+                        _ => throw new NotSupportedException($"Unsupported request of type {approvalRequest.GetType().Name}"),
+                    };
+            }
+        }
+    }
+
     private static string? ParseWorkflowFile(string[] args)
     {
         string? workflowFile = args.FirstOrDefault();

dotnet/samples/GettingStarted/Workflows/HumanInTheLoop/HumanInTheLoopBasic/Program.cs

@@ -24,7 +24,7 @@ public static class Program
     private static async Task Main()
     {
         // Create the workflow
-        var workflow = await WorkflowHelper.GetWorkflowAsync();
+        var workflow = WorkflowFactory.BuildWorkflow();
 
         // Execute the workflow
         await using StreamingRun handle = await InProcessExecution.StreamAsync(workflow, NumberSignal.Init);