Added AI Search example

Merge branch 'main' into feature-python-foundry-agents
Addressed PR feedback
2026-06-16 21:04:09 +08:00 · 2025-11-12 13:59:31 -08:00 · 2025-11-12 12:59:17 -08:00 · 2025-11-12 12:48:23 -08:00 · 2025-11-12 11:54:40 -08:00 · 2025-11-12 19:52:05 +00:00
135 changed files with 8154 additions and 2200 deletions
@@ -8,11 +8,11 @@ name: dotnet-build-and-test
 on:
  workflow_dispatch:
  pull_request:
-    branches: ["main"]
+    branches: ["main", "feature*"]
  merge_group:
-    branches: ["main"]
+    branches: ["main", "feature*"]
  push:
-    branches: ["main"]
+    branches: ["main", "feature*"]
  schedule:
    - cron: "0 0 * * *" # Run at midnight UTC daily

@@ -39,7 +39,7 @@ jobs:
          echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
      - name: Pytest coverage comment
        id: coverageComment
-        uses: MishaKav/pytest-coverage-comment@v1.1.57
+        uses: MishaKav/pytest-coverage-comment@v1.1.59
        with:
          github-token: ${{ secrets.GH_ACTIONS_PR_WRITE }}
          issue-number: ${{ env.PR_NUMBER }}
@@ -7,33 +7,33 @@
  </PropertyGroup>
  <PropertyGroup>
    <!-- Aspire -->
-    <AspireAppHostSdkVersion>9.5.2</AspireAppHostSdkVersion>
+    <AspireAppHostSdkVersion>13.0.0</AspireAppHostSdkVersion>
  </PropertyGroup>
  <ItemGroup>
    <!-- Aspire.* -->
-    <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="9.5.1-preview.1.25502.11" />
+    <PackageVersion Include="Aspire.Azure.AI.OpenAI" Version="13.0.0-preview.1.25560.3" />
    <PackageVersion Include="Aspire.Hosting.AppHost" Version="$(AspireAppHostSdkVersion)" />
    <PackageVersion Include="Aspire.Hosting.Azure.CognitiveServices" Version="$(AspireAppHostSdkVersion)" />
    <PackageVersion Include="Aspire.Microsoft.Azure.Cosmos" Version="$(AspireAppHostSdkVersion)" />
-    <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="9.9.0" />
+    <PackageVersion Include="CommunityToolkit.Aspire.OllamaSharp" Version="13.0.0-beta.435" />
    <!-- Azure.* -->
    <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.AsyncInterfaces" Version="10.0.0" />
    <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.ClientModel" Version="1.8.0" />
+    <PackageVersion Include="System.CodeDom" Version="10.0.0" />
+    <PackageVersion Include="System.Collections.Immutable" Version="10.0.0" />
    <PackageVersion Include="System.CommandLine" Version="2.0.0-rc.2.25502.107" />
-    <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="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.Diagnostics.DiagnosticSource" Version="10.0.0" />
+    <PackageVersion Include="System.Linq.AsyncEnumerable" Version="10.0.0" />
+    <PackageVersion Include="System.Net.Http.Json" Version="10.0.0" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.0" />
+    <PackageVersion Include="System.Text.Json" Version="10.0.0" />
+    <PackageVersion Include="System.Threading.Channels" Version="10.0.0" />
    <PackageVersion Include="System.Threading.Tasks.Extensions" Version="4.6.3" />
    <!-- OpenTelemetry -->
    <PackageVersion Include="OpenTelemetry" Version="1.13.1" />
@@ -44,39 +44,39 @@
    <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" />
+    <PackageVersion Include="OpenTelemetry.Instrumentation.Runtime" Version="1.13.0" />
    <!-- Microsoft.AspNetCore.* -->
-    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="9.0.10" />
-    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="9.0.4" />
+    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="9.0.11" />
+    <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.0.0" />
    <!-- Microsoft.Extensions.* -->
-    <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.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" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="9.0.10" />
-    <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="9.0.10" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="9.0.10" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="9.0.10" />
-    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="9.0.10" />
-    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="9.10.0" />
-    <PackageVersion Include="Microsoft.Extensions.Logging" Version="9.0.10" />
-    <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.AI" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.AI.AzureAIInference" Version="10.0.0-preview.1.25559.3" />
+    <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.0.0-preview.1.25559.3" />
+    <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Binder" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.Json" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Console" Version="10.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.VectorData.Abstractions" Version="9.7.0" />
-    <!-- Semantic Kernel -->
-    <PackageVersion Include="Microsoft.SemanticKernel" Version="1.66.0" />
-    <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" />
-    <PackageVersion Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.66.0" />
    <!-- Vector Stores -->
-    <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.Connectors.InMemory" Version="1.67.0-preview" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Connectors.Qdrant" Version="1.67.0-preview" />
+    <!-- Semantic Kernel -->
+    <PackageVersion Include="Microsoft.SemanticKernel" Version="1.67.0" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Agents.Core" Version="1.67.0" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Agents.OpenAI" Version="1.67.0-preview" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Agents.AzureAI" Version="1.67.0-preview" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Plugins.OpenApi" Version="1.67.0" />
    <!-- Agent SDKs -->
    <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.2.41" />
    <!-- A2A -->
@@ -101,11 +101,11 @@
    <PackageVersion Include="System.Linq.Async" Version="6.0.3" />
    <!-- Test -->
    <PackageVersion Include="FluentAssertions" Version="8.8.0" />
-    <PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="9.0.10" />
+    <PackageVersion Include="Microsoft.AspNetCore.TestHost" Version="9.0.11" />
    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.0.0" />
    <PackageVersion Include="Moq" Version="[4.18.4]" />
-    <PackageVersion Include="Microsoft.SemanticKernel.Agents.Abstractions" Version="1.66.0" />
-    <PackageVersion Include="Microsoft.SemanticKernel.Agents.Yaml" Version="1.66.0-beta" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Agents.Abstractions" Version="1.67.0" />
+    <PackageVersion Include="Microsoft.SemanticKernel.Agents.Yaml" Version="1.67.0-beta" />
    <PackageVersion Include="xunit" Version="2.9.3" />
    <PackageVersion Include="xunit.abstractions" Version="2.0.3" />
    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.3" />
@@ -115,7 +115,7 @@
    <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
    <!-- Toolset -->
    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" />
-    <PackageVersion Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="9.0.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.100" />
    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
@@ -135,7 +135,7 @@
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
-    <PackageVersion Include="Roslynator.Analyzers" Version="[4.14.0]" />
+    <PackageVersion Include="Roslynator.Analyzers" Version="[4.14.1]" />
    <PackageReference Include="Roslynator.Analyzers">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
@@ -63,6 +63,7 @@
    <Project Path="samples/GettingStarted/Agents/Agent_Step15_Plugins/Agent_Step15_Plugins.csproj" />
    <Project Path="samples/GettingStarted/Agents/Agent_Step16_ChatReduction/Agent_Step16_ChatReduction.csproj" />
    <Project Path="samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/Agent_Step17_BackgroundResponses.csproj" />
+    <Project Path="samples/GettingStarted/Agents/Agent_Step18_DeepResearch/Agent_Step18_DeepResearch.csproj" />
  </Folder>
  <Folder Name="/Samples/GettingStarted/DevUI/">
    <File Path="samples/GettingStarted/DevUI/README.md" />
@@ -158,10 +159,10 @@
    <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/Catalog/">
-    <Project Path="samples/Catalog/AgentsInWorkflows/AgentsInWorkflows.csproj" />
-    <Project Path="samples/Catalog/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
-    <Project Path="samples/Catalog/DeepResearchAgent/DeepResearchAgent.csproj" />
+  <Folder Name="/Samples/HostedAgents/">
+    <Project Path="samples/HostedAgents/AgentsInWorkflows/AgentsInWorkflows.csproj" />
+    <Project Path="samples/HostedAgents/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />
+    <Project Path="samples/HostedAgents/AgentWithHostedMCP/AgentWithHostedMCP.csproj" />
  </Folder>
  <Folder Name="/Solution Items/">
    <File Path=".editorconfig" />
@@ -2,9 +2,9 @@
  <PropertyGroup>
    <!-- Central version prefix - applies to all nuget packages. -->
    <VersionPrefix>1.0.0</VersionPrefix>
-    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).251107.2</PackageVersion>
-    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.251107.2</PackageVersion>
-    <GitTag>1.0.0-preview.251107.2</GitTag>
+    <PackageVersion Condition="'$(VersionSuffix)' != ''">$(VersionPrefix)-$(VersionSuffix).251110.2</PackageVersion>
+    <PackageVersion Condition="'$(VersionSuffix)' == ''">$(VersionPrefix)-preview.251110.2</PackageVersion>
+    <GitTag>1.0.0-preview.251110.2</GitTag>

    <Configurations>Debug;Release;Publish</Configurations>
    <IsPackable>true</IsPackable>
@@ -1,21 +0,0 @@
-<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>
@@ -1,23 +0,0 @@
-<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>
@@ -142,11 +142,11 @@ You:
 Besides the Aspire Dashboard and the Application Insights native UI, you can also use Grafana to visualize the telemetry data in Application Insights. There are two tailored dashboards for you to get started quickly:

 ### Agent Overview dashboard
-Grafana Dashboard Gallery link: <https://aka.ms/amg/dash/af-agent>
+Open dashboard in Azure portal: <https://aka.ms/amg/dash/af-agent>
 ![Agent Overview dashboard](https://github.com/Azure/azure-managed-grafana/raw/main/samples/assets/grafana-af-agent.gif)

 ### Workflow Overview dashboard
-Grafana Dashboard Gallery link: <https://aka.ms/amg/dash/af-workflow>
+Open dashboard in Azure portal: <https://aka.ms/amg/dash/af-workflow>
 ![Workflow Overview dashboard](https://github.com/Azure/azure-managed-grafana/raw/main/samples/assets/grafana-af-workflow.gif)

 ## Key Features Demonstrated
@@ -14,7 +14,7 @@
  </ItemGroup>

  <ItemGroup>
-    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
  </ItemGroup>

 </Project>
@@ -44,6 +44,7 @@ Before you begin, ensure you have the following prerequisites:
 |[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|
+|[Deep research with an agent](./Agent_Step18_DeepResearch/)|This sample demonstrates how to use the Deep Research Tool to perform comprehensive research on complex topics|

 ## Running the samples from the console

@@ -16,7 +16,7 @@ internal static class WorkflowFactory
    internal static Workflow BuildWorkflow(IChatClient chatClient)
    {
        // Create executors
-        var startExecutor = new ConcurrentStartExecutor();
+        var startExecutor = new ChatForwardingExecutor("Start");
        var aggregationExecutor = new ConcurrentAggregationExecutor();
        AIAgent frenchAgent = GetLanguageAgent("French", chatClient);
        AIAgent englishAgent = GetLanguageAgent("English", chatClient);
@@ -38,33 +38,11 @@ internal static class WorkflowFactory
    private static ChatClientAgent GetLanguageAgent(string targetLanguage, IChatClient chatClient) =>
        new(chatClient, instructions: $"You're a helpful assistant who always responds in {targetLanguage}.", name: $"{targetLanguage}Agent");

-    /// <summary>
-    /// Executor that starts the concurrent processing by sending messages to the agents.
-    /// </summary>
-    private sealed class ConcurrentStartExecutor() : Executor("ConcurrentStartExecutor")
-    {
-        protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder)
-        {
-            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<List<ChatMessage>>("ConcurrentAggregationExecutor")
+    private sealed class ConcurrentAggregationExecutor() :
+        Executor<List<ChatMessage>>("ConcurrentAggregationExecutor"), IResettableExecutor
    {
        private readonly List<ChatMessage> _messages = [];

@@ -85,5 +63,12 @@ internal static class WorkflowFactory
                await context.YieldOutputAsync(formattedMessages, cancellationToken);
            }
        }
+
+        /// <inheritdoc/>
+        public ValueTask ResetAsync()
+        {
+            this._messages.Clear();
+            return default;
+        }
    }
 }
@@ -42,7 +42,7 @@ internal sealed class Program
        Console.WriteLine(code);
    }

-    private const string DefaultWorkflow = "HelloWorld.yaml";
+    private const string DefaultWorkflow = "Marketing.yaml";

    private string WorkflowFile { get; }

@@ -92,11 +92,11 @@ The repository has example workflows available in the root [`/workflow-samples`]
 2. Run the demo referencing a sample workflow by name:

    ```sh
-    dotnet run HelloWorld
+    dotnet run Marketing
    ```

 3. Run the demo with a path to any workflow file:

    ```sh
-    dotnet run c:/myworkflows/HelloWorld.yaml
+    dotnet run c:/myworkflows/Marketing.yaml
    ```
@@ -0,0 +1,69 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+
+    <!-- 
+        Disable central package management for this project.
+        This project requires explicit package references with versions specified inline rather than 
+        inheriting them from Directory.Packages.props. This is necessary because a Docker image will 
+        be created from this project, and the Docker build process only has access to this folder 
+        and cannot access parent folders where Directory.Packages.props resides.
+    -->
+    <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+
+  <!-- 
+    Remove analyzer PackageReference items inherited from Directory.Packages.props.
+    Note: ManagePackageVersionsCentrally only controls PackageVersion items, not PackageReference items.
+    Directory.Packages.props contains both PackageVersion and PackageReference entries for analyzers,
+    and the PackageReference items are always inherited through MSBuild imports regardless of the 
+    ManagePackageVersionsCentrally setting. We must explicitly remove them before adding our own versions.
+  -->
+  <ItemGroup>
+    <PackageReference Remove="Microsoft.CodeAnalysis.NetAnalyzers" />
+    <PackageReference Remove="Microsoft.VisualStudio.Threading.Analyzers" />
+    <PackageReference Remove="xunit.analyzers" />
+    <PackageReference Remove="Moq.Analyzers" />
+    <PackageReference Remove="Roslynator.Analyzers" />
+    <PackageReference Remove="Roslynator.CodeAnalysis.Analyzers" />
+    <PackageReference Remove="Roslynator.Formatting.Analyzers" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.AgentServer.AgentFramework" Version="1.0.0-beta.4" />
+    <PackageReference Include="Azure.AI.OpenAI" Version="2.5.0-beta.1" />
+    <PackageReference Include="Azure.Identity" Version="1.17.0" />
+    <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0-preview.251110.2" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.10.2-preview.1.25552.1" />
+  </ItemGroup>
+
+  <!-- Add analyzers with compatible versions -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="9.0.0">
+      <PrivateAssets>all</PrivateAssets>
+    <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Microsoft.VisualStudio.Threading.Analyzers" Version="17.14.15">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Analyzers" Version="4.12.9">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.CodeAnalysis.Analyzers" Version="4.12.9">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Formatting.Analyzers" Version="4.12.9">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,20 @@
+# Build the application
+FROM mcr.microsoft.com/dotnet/sdk:9.0-alpine AS build
+WORKDIR /src
+
+# Copy files from the current directory on the host to the working directory in the container
+COPY . .
+
+RUN dotnet restore
+RUN dotnet build -c Release --no-restore
+RUN dotnet publish -c Release --no-build -o /app
+
+# Run the application
+FROM mcr.microsoft.com/dotnet/aspnet:9.0-alpine AS final
+WORKDIR /app
+
+# Copy everything needed to run the app from the "build" stage.
+COPY --from=build /app .
+
+EXPOSE 8088
+ENTRYPOINT ["dotnet", "AgentWithHostedMCP.dll"]
@@ -0,0 +1,34 @@
+// 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 demonstrates how to use MCP tools with auto approval by setting ApprovalMode to NeverRequire.
+
+using Azure.AI.AgentServer.AgentFramework.Extensions;
+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";
+
+// Create an MCP tool that can be called without approval.
+AITool mcpTool = new HostedMcpServerTool(serverName: "microsoft_learn", serverAddress: "https://learn.microsoft.com/api/mcp")
+{
+    AllowedTools = ["microsoft_docs_search"],
+    ApprovalMode = HostedMcpServerToolApprovalMode.NeverRequire
+};
+
+// Create an agent with the MCP tool using Azure OpenAI Responses.
+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]);
+
+await agent.RunAIAgentAsync();
@@ -0,0 +1,43 @@
+# What this sample demonstrates
+
+This sample demonstrates how to use a Hosted Model Context Protocol (MCP) server with an AI agent.
+The agent connects to the Microsoft Learn MCP server to search documentation and answer questions using official Microsoft content.
+
+Key features:
+- Configuring MCP tools with automatic approval (no user confirmation required)
+- Filtering available tools from an MCP server
+- Using Azure OpenAI Responses with MCP tools
+
+## 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
+
+**Note**: This sample uses Azure CLI credentials for authentication. Make sure you're logged in with `az login` and have access to the Azure OpenAI resource.
+
+## 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 connects to the Microsoft Learn MCP server and uses its documentation search capabilities:
+
+1. The agent is configured with a HostedMcpServerTool pointing to `https://learn.microsoft.com/api/mcp`
+2. Only the `microsoft_docs_search` tool is enabled from the available MCP tools
+3. Approval mode is set to `NeverRequire`, allowing automatic tool execution
+4. When you ask questions, Azure OpenAI Responses automatically invokes the MCP tool to search documentation
+5. The agent returns answers based on the Microsoft Learn content
+
+In this configuration, the OpenAI Responses service manages tool invocation directly - the Agent Framework does not handle MCP tool calls.
@@ -0,0 +1,29 @@
+name: AgentWithHostedMCP
+displayName: "Microsoft Learn Response Agent with MCP"
+description: >
+  An AI agent that uses Azure OpenAI Responses with a Hosted Model Context Protocol (MCP) server.
+  The agent answers questions by searching Microsoft Learn documentation using MCP tools.
+  This demonstrates how MCP tools can be integrated with Azure OpenAI Responses where the service
+  itself handles tool invocation.
+metadata:
+  authors:
+    - Microsoft Agent Framework Team
+  tags:
+    - Microsoft Agent Framework
+    - Model Context Protocol
+    - MCP
+template:
+  kind: hosted
+  name: AgentWithHostedMCP
+  protocols:
+    - protocol: responses
+      version: v1
+  environment_variables:
+    - name: AZURE_OPENAI_ENDPOINT
+      value: ${AZURE_OPENAI_ENDPOINT}
+    - name: AZURE_OPENAI_DEPLOYMENT_NAME
+      value: gpt-4o-mini
+resources:
+  - name: "gpt-4o-mini"
+    kind: model
+    id: gpt-4o-mini
@@ -0,0 +1,30 @@
+@host = http://localhost:8088
+@endpoint = {{host}}/responses
+
+### Health Check
+GET {{host}}/readiness
+
+### Simple string input - Ask about MCP Tools
+POST {{endpoint}}
+Content-Type: application/json
+{
+    "input": "Please summarize the Azure AI Agent documentation related to MCP Tool calling?"
+}
+
+### Explicit input - Ask about Agent Framework
+POST {{endpoint}}
+Content-Type: application/json
+{
+    "input": [
+        {
+            "type": "message",
+            "role": "user",
+            "content": [
+                {
+                    "type": "input_text",
+                    "text": "What is the Microsoft Agent Framework?"
+                }
+            ]
+        }
+    ]
+}
@@ -0,0 +1,69 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+
+    <!-- 
+      Disable central package management for this project.
+      This project requires explicit package references with versions specified inline rather than 
+      inheriting them from Directory.Packages.props. This is necessary because a Docker image will 
+      be created from this project, and the Docker build process only has access to this folder 
+      and cannot access parent folders where Directory.Packages.props resides.
+    -->
+    <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+
+  <!-- 
+    Remove analyzer PackageReference items inherited from Directory.Packages.props.
+    Note: ManagePackageVersionsCentrally only controls PackageVersion items, not PackageReference items.
+    Directory.Packages.props contains both PackageVersion and PackageReference entries for analyzers,
+    and the PackageReference items are always inherited through MSBuild imports regardless of the 
+    ManagePackageVersionsCentrally setting. We must explicitly remove them before adding our own versions.
+  -->
+  <ItemGroup>
+    <PackageReference Remove="Microsoft.CodeAnalysis.NetAnalyzers" />
+    <PackageReference Remove="Microsoft.VisualStudio.Threading.Analyzers" />
+    <PackageReference Remove="xunit.analyzers" />
+    <PackageReference Remove="Moq.Analyzers" />
+    <PackageReference Remove="Roslynator.Analyzers" />
+    <PackageReference Remove="Roslynator.CodeAnalysis.Analyzers" />
+    <PackageReference Remove="Roslynator.Formatting.Analyzers" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.AgentServer.AgentFramework" Version="1.0.0-beta.4" />
+    <PackageReference Include="Azure.AI.OpenAI" Version="2.5.0-beta.1" />
+    <PackageReference Include="Azure.Identity" Version="1.17.0" />
+    <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0-preview.251110.2" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.10.2-preview.1.25552.1" />
+  </ItemGroup>
+
+  <!-- Add analyzers with compatible versions -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="9.0.0">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Microsoft.VisualStudio.Threading.Analyzers" Version="17.14.15">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Analyzers" Version="4.12.9">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.CodeAnalysis.Analyzers" Version="4.12.9">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Formatting.Analyzers" Version="4.12.9">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,20 @@
+# Build the application
+FROM mcr.microsoft.com/dotnet/sdk:9.0-alpine AS build
+WORKDIR /src
+
+# Copy files from the current directory on the host to the working directory in the container
+COPY . .
+
+RUN dotnet restore
+RUN dotnet build -c Release --no-restore
+RUN dotnet publish -c Release --no-build -o /app
+
+# Run the application
+FROM mcr.microsoft.com/dotnet/aspnet:9.0-alpine AS final
+WORKDIR /app
+
+# Copy everything needed to run the app from the "build" stage.
+COPY --from=build /app .
+
+EXPOSE 8088
+ENTRYPOINT ["dotnet", "AgentWithTextSearchRag.dll"]
@@ -4,6 +4,7 @@
 // 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.AgentServer.AgentFramework.Extensions;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
@@ -23,7 +24,7 @@ TextSearchProviderOptions textSearchOptions = new()

 AIAgent agent = new AzureOpenAIClient(
    new Uri(endpoint),
-    new AzureCliCredential())
+    new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .CreateAIAgent(new ChatClientAgentOptions
    {
@@ -31,16 +32,7 @@ AIAgent agent = new AzureOpenAIClient(
        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));
+await agent.RunAIAgentAsync();

 static Task<IEnumerable<TextSearchProvider.TextSearchResult>> MockSearchAsync(string query, CancellationToken cancellationToken)
 {
@@ -0,0 +1,30 @@
+name: AgentWithTextSearchRag
+displayName: "Text Search RAG Agent"
+description: >
+  An AI agent that uses TextSearchProvider for retrieval augmented generation (RAG) capabilities.
+  The agent runs searches against an external knowledge base before each model invocation and
+  injects the results into the model context. It can answer questions about Contoso Outdoors
+  policies and products, including return policies, refunds, shipping options, and product care
+  instructions such as tent maintenance.
+metadata:
+  authors:
+    - Microsoft Agent Framework Team
+  tags:
+    - Microsoft Agent Framework
+    - Retrieval-Augmented Generation
+    - RAG
+template:
+  kind: hosted
+  name: AgentWithTextSearchRag
+  protocols:
+    - protocol: responses
+      version: v1
+  environment_variables:
+    - name: AZURE_OPENAI_ENDPOINT
+      value: ${AZURE_OPENAI_ENDPOINT}
+    - name: AZURE_OPENAI_DEPLOYMENT_NAME
+      value: gpt-4o-mini
+resources:
+  - name: "gpt-4o-mini"
+    kind: model
+    id: gpt-4o-mini
@@ -0,0 +1,30 @@
+@host = http://localhost:8088
+@endpoint = {{host}}/responses
+
+### Health Check
+GET {{host}}/readiness
+
+### Simple string input
+POST {{endpoint}}
+Content-Type: application/json
+{
+    "input": "Hi! I need help understanding the return policy."
+}
+
+### Explicit input
+POST {{endpoint}}
+Content-Type: application/json
+{
+    "input": [
+        {
+            "type": "message",
+            "role": "user",
+            "content": [
+                {
+                    "type": "input_text",
+                    "text": "How long does standard shipping usually take?"
+                }
+            ]
+        }
+    ]
+}
@@ -0,0 +1,69 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net9.0</TargetFramework>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+
+    <!-- 
+      Disable central package management for this project.
+      This project requires explicit package references with versions specified inline rather than 
+      inheriting them from Directory.Packages.props. This is necessary because a Docker image will 
+      be created from this project, and the Docker build process only has access to this folder 
+      and cannot access parent folders where Directory.Packages.props resides.
+    -->
+    <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+
+  <!-- 
+    Remove analyzer PackageReference items inherited from Directory.Packages.props.
+    Note: ManagePackageVersionsCentrally only controls PackageVersion items, not PackageReference items.
+    Directory.Packages.props contains both PackageVersion and PackageReference entries for analyzers,
+    and the PackageReference items are always inherited through MSBuild imports regardless of the 
+    ManagePackageVersionsCentrally setting. We must explicitly remove them before adding our own versions.
+  -->
+  <ItemGroup>
+    <PackageReference Remove="Microsoft.CodeAnalysis.NetAnalyzers" />
+    <PackageReference Remove="Microsoft.VisualStudio.Threading.Analyzers" />
+    <PackageReference Remove="xunit.analyzers" />
+    <PackageReference Remove="Moq.Analyzers" />
+    <PackageReference Remove="Roslynator.Analyzers" />
+    <PackageReference Remove="Roslynator.CodeAnalysis.Analyzers" />
+    <PackageReference Remove="Roslynator.Formatting.Analyzers" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.AgentServer.AgentFramework" Version="1.0.0-beta.4" />
+    <PackageReference Include="Azure.AI.OpenAI" Version="2.5.0-beta.1" />
+    <PackageReference Include="Azure.Identity" Version="1.17.0" />
+    <PackageReference Include="Microsoft.Agents.AI.Workflows" Version="1.0.0-preview.251110.2" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.10.2-preview.1.25552.1" />
+  </ItemGroup>
+
+  <!-- Add analyzers with compatible versions -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="9.0.0">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Microsoft.VisualStudio.Threading.Analyzers" Version="17.14.15">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Analyzers" Version="4.12.9">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.CodeAnalysis.Analyzers" Version="4.12.9">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+    <PackageReference Include="Roslynator.Formatting.Analyzers" Version="4.12.9">
+      <PrivateAssets>all</PrivateAssets>
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+    </PackageReference>
+  </ItemGroup>
+
+</Project>
@@ -0,0 +1,20 @@
+# Build the application
+FROM mcr.microsoft.com/dotnet/sdk:9.0-alpine AS build
+WORKDIR /src
+
+# Copy files from the current directory on the host to the working directory in the container
+COPY . .
+
+RUN dotnet restore
+RUN dotnet build -c Release --no-restore
+RUN dotnet publish -c Release --no-build -o /app
+
+# Run the application
+FROM mcr.microsoft.com/dotnet/aspnet:9.0-alpine AS final
+WORKDIR /app
+
+# Copy everything needed to run the app from the "build" stage.
+COPY --from=build /app .
+
+EXPOSE 8088
+ENTRYPOINT ["dotnet", "AgentsInWorkflows.dll"]
@@ -4,6 +4,7 @@
 // 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.AgentServer.AgentFramework.Extensions;
 using Azure.AI.OpenAI;
 using Azure.Identity;
 using Microsoft.Agents.AI;
@@ -14,7 +15,7 @@ using Microsoft.Extensions.AI;
 var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
 var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

-IChatClient chatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential())
+IChatClient chatClient = new AzureOpenAIClient(new Uri(endpoint), new DefaultAzureCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();

@@ -23,26 +24,14 @@ 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)
+// Build the workflow and turn it into an agent
+AIAgent agent = new WorkflowBuilder(frenchAgent)
    .AddEdge(frenchAgent, spanishAgent)
    .AddEdge(spanishAgent, englishAgent)
-.Build();
+    .Build()
+    .AsAgent();

-// 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}");
-    }
-}
+await agent.RunAIAgentAsync();

 static ChatClientAgent GetTranslationAgent(string targetLanguage, IChatClient chatClient) =>
    new(chatClient, $"You are a translation assistant that translates the provided text to {targetLanguage}.");
@@ -0,0 +1,27 @@
+name: AgentsInWorkflows
+displayName: "Translation Chain Workflow Agent"
+description: >
+  A workflow agent that performs sequential translation through multiple languages.
+  The agent translates text from English to French, then to Spanish, and finally back
+  to English, leveraging AI-powered translation capabilities in a pipeline workflow.
+metadata:
+  authors:
+    - Microsoft Agent Framework Team
+  tags:
+    - Microsoft Agent Framework
+    - Workflows
+template:
+  kind: hosted
+  name: AgentsInWorkflows
+  protocols:
+    - protocol: responses
+      version: v1
+  environment_variables:
+    - name: AZURE_OPENAI_ENDPOINT
+      value: ${AZURE_OPENAI_ENDPOINT}
+    - name: AZURE_OPENAI_DEPLOYMENT_NAME
+      value: gpt-4o-mini
+resources:
+  - name: "gpt-4o-mini"
+    kind: model
+    id: gpt-4o-mini
@@ -0,0 +1,30 @@
+@host = http://localhost:8088
+@endpoint = {{host}}/responses
+
+### Health Check
+GET {{host}}/readiness
+
+### Simple string input
+POST {{endpoint}}
+Content-Type: application/json
+{
+    "input": "Hello, how are you today?"
+}
+
+### Explicit input
+POST {{endpoint}}
+Content-Type: application/json
+{
+    "input": [
+        {
+            "type": "message",
+            "role": "user",
+            "content": [
+                {
+                    "type": "input_text",
+                    "text": "Hello, how are you today?"
+                }
+            ]
+        }
+    ]
+}
@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.

 using System;
+using Microsoft.Extensions.AI;
 using Microsoft.Shared.Diagnostics;

 namespace Microsoft.Agents.AI;
@@ -32,6 +33,7 @@ public class AgentRunOptions
        _ = Throw.IfNull(options);
        this.ContinuationToken = options.ContinuationToken;
        this.AllowBackgroundResponses = options.AllowBackgroundResponses;
+        this.AdditionalProperties = options.AdditionalProperties?.Clone();
    }

    /// <summary>
@@ -74,4 +76,18 @@ public class AgentRunOptions
    /// </para>
    /// </remarks>
    public bool? AllowBackgroundResponses { get; set; }
+
+    /// <summary>
+    /// Gets or sets additional properties associated with these options.
+    /// </summary>
+    /// <value>
+    /// An <see cref="AdditionalPropertiesDictionary"/> containing custom properties,
+    /// or <see langword="null"/> if no additional properties are present.
+    /// </value>
+    /// <remarks>
+    /// Additional properties provide a way to include custom metadata or provider-specific
+    /// information that doesn't fit into the standard options schema. This is useful for
+    /// preserving implementation-specific details or extending the options with custom data.
+    /// </remarks>
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
 }
@@ -160,5 +160,5 @@ internal sealed record CustomToolFormat
    /// Additional format properties (schema definition).
    /// </summary>
    [JsonExtensionData]
-    public Dictionary<string, object?>? AdditionalProperties { get; init; }
+    public Dictionary<string, object?>? AdditionalProperties { get; set; }
 }
@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.Workflows;
+
+/// <summary>
+/// Provides configuration options for <see cref="ChatForwardingExecutor"/>.
+/// </summary>
+public class ChatForwardingExecutorOptions
+{
+    /// <summary>
+    /// Gets or sets the chat role to use when converting string messages to <see cref="ChatMessage"/> instances.
+    /// If set, the executor will accept string messages and convert them to chat messages with this role.
+    /// </summary>
+    public ChatRole? StringMessageChatRole { get; set; }
+}
+
+/// <summary>
+/// A ChatProtocol executor that forwards all messages it receives. Useful for splitting inputs into parallel
+/// processing paths.
+/// </summary>
+/// <remarks>This executor is designed to be cross-run shareable and can be reset to its initial state. It handles
+/// multiple chat-related types, enabling flexible message forwarding scenarios. Thread safety and reusability are
+/// ensured by its design.</remarks>
+/// <param name="id">The unique identifier for the executor instance. Used to distinguish this executor within the system.</param>
+/// <param name="options">Optional configuration settings for the executor. If null, default options are used.</param>
+public sealed class ChatForwardingExecutor(string id, ChatForwardingExecutorOptions? options = null) : Executor(id, declareCrossRunShareable: true), IResettableExecutor
+{
+    private readonly ChatRole? _stringMessageChatRole = options?.StringMessageChatRole;
+
+    /// <inheritdoc/>
+    protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder)
+    {
+        if (this._stringMessageChatRole.HasValue)
+        {
+            routeBuilder = routeBuilder.AddHandler<string>(
+                (message, context) => context.SendMessageAsync(new ChatMessage(ChatRole.User, message)));
+        }
+
+        return routeBuilder.AddHandler<ChatMessage>(ForwardMessageAsync)
+                           .AddHandler<IEnumerable<ChatMessage>>(ForwardMessagesAsync)
+                           .AddHandler<ChatMessage[]>(ForwardMessagesAsync)
+                           .AddHandler<List<ChatMessage>>(ForwardMessagesAsync)
+                           .AddHandler<TurnToken>(ForwardTurnTokenAsync);
+    }
+
+    private static ValueTask ForwardMessageAsync(ChatMessage message, IWorkflowContext context, CancellationToken cancellationToken)
+        => context.SendMessageAsync(message, cancellationToken);
+
+    // Note that this can be used to split a turn into multiple parallel turns taken, which will cause streaming ChatMessages
+    // to overlap.
+    private static ValueTask ForwardTurnTokenAsync(TurnToken message, IWorkflowContext context, CancellationToken cancellationToken)
+        => context.SendMessageAsync(message, cancellationToken);
+
+    // TODO: This is not ideal, but until we have a way of guaranteeing correct routing of interfaces across serialization
+    // boundaries, we need to do type unification. It behaves better when used as a handler in ChatProtocolExecutor because
+    // it is a strictly contravariant use, whereas this forces invariance on the type because it is directly forwarded.
+    private static ValueTask ForwardMessagesAsync(IEnumerable<ChatMessage> messages, IWorkflowContext context, CancellationToken cancellationToken)
+        => context.SendMessageAsync(messages is List<ChatMessage> messageList ? messageList : messages.ToList(), cancellationToken);
+
+    private static ValueTask ForwardMessagesAsync(ChatMessage[] messages, IWorkflowContext context, CancellationToken cancellationToken)
+        => context.SendMessageAsync(messages, cancellationToken);
+
+    /// <inheritdoc/>
+    public ValueTask ResetAsync() => default;
+}
@@ -1,20 +0,0 @@
-// Copyright (c) Microsoft. All rights reserved.
-
-using System.Collections.Generic;
-using System.Threading.Tasks;
-using Microsoft.Extensions.AI;
-
-namespace Microsoft.Agents.AI.Workflows.Specialized;
-
-/// <summary>Executor that forwards all messages.</summary>
-internal sealed class ChatForwardingExecutor(string id) : Executor(id, declareCrossRunShareable: true), IResettableExecutor
-{
-    protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder) =>
-        routeBuilder
-                .AddHandler<string>((message, context, cancellationToken) => context.SendMessageAsync(new ChatMessage(ChatRole.User, message), cancellationToken: cancellationToken))
-                .AddHandler<ChatMessage>((message, context, cancellationToken) => context.SendMessageAsync(message, cancellationToken: cancellationToken))
-                .AddHandler<List<ChatMessage>>((messages, context, cancellationToken) => context.SendMessageAsync(messages, cancellationToken: cancellationToken))
-                .AddHandler<TurnToken>((turnToken, context, cancellationToken) => context.SendMessageAsync(turnToken, cancellationToken: cancellationToken));
-
-    public ValueTask ResetAsync() => default;
-}
@@ -18,7 +18,12 @@ public class AgentRunOptionsTests
        var options = new AgentRunOptions
        {
            ContinuationToken = new object(),
-            AllowBackgroundResponses = true
+            AllowBackgroundResponses = true,
+            AdditionalProperties = new AdditionalPropertiesDictionary
+            {
+                ["key1"] = "value1",
+                ["key2"] = 42
+            }
        };

        // Act
@@ -28,6 +33,10 @@ public class AgentRunOptionsTests
        Assert.NotNull(clone);
        Assert.Same(options.ContinuationToken, clone.ContinuationToken);
        Assert.Equal(options.AllowBackgroundResponses, clone.AllowBackgroundResponses);
+        Assert.NotNull(clone.AdditionalProperties);
+        Assert.NotSame(options.AdditionalProperties, clone.AdditionalProperties);
+        Assert.Equal("value1", clone.AdditionalProperties["key1"]);
+        Assert.Equal(42, clone.AdditionalProperties["key2"]);
    }

    [Fact]
@@ -42,7 +51,12 @@ public class AgentRunOptionsTests
        var options = new AgentRunOptions
        {
            ContinuationToken = ResponseContinuationToken.FromBytes(new byte[] { 1, 2, 3 }),
-            AllowBackgroundResponses = true
+            AllowBackgroundResponses = true,
+            AdditionalProperties = new AdditionalPropertiesDictionary
+            {
+                ["key1"] = "value1",
+                ["key2"] = 42
+            }
        };

        // Act
@@ -54,5 +68,13 @@ public class AgentRunOptionsTests
        Assert.NotNull(deserialized);
        Assert.Equivalent(ResponseContinuationToken.FromBytes(new byte[] { 1, 2, 3 }), deserialized!.ContinuationToken);
        Assert.Equal(options.AllowBackgroundResponses, deserialized.AllowBackgroundResponses);
+        Assert.NotNull(deserialized.AdditionalProperties);
+        Assert.Equal(2, deserialized.AdditionalProperties.Count);
+        Assert.True(deserialized.AdditionalProperties.TryGetValue("key1", out object? value1));
+        Assert.IsType<JsonElement>(value1);
+        Assert.Equal("value1", ((JsonElement)value1!).GetString());
+        Assert.True(deserialized.AdditionalProperties.TryGetValue("key2", out object? value2));
+        Assert.IsType<JsonElement>(value2);
+        Assert.Equal(42, ((JsonElement)value2!).GetInt32());
    }
 }
@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+## [1.0.0b251111] - 2025-11-11
+
+### Added
+
+- **agent-framework-core**: Add OpenAI Responses Image Generation Stream Support with partial images and unit tests ([#1853](https://github.com/microsoft/agent-framework/pull/1853))
+- **agent-framework-ag-ui**: Add concrete AGUIChatClient implementation ([#2072](https://github.com/microsoft/agent-framework/pull/2072))
+
+### Fixed
+
+- **agent-framework-a2a**: Use the last entry in the task history to avoid empty responses ([#2101](https://github.com/microsoft/agent-framework/pull/2101))
+- **agent-framework-core**: Fix MCP Tool Parameter Descriptions not propagated to LLMs ([#1978](https://github.com/microsoft/agent-framework/pull/1978))
+- **agent-framework-core**: Handle agent user input request in AgentExecutor ([#2022](https://github.com/microsoft/agent-framework/pull/2022))
+- **agent-framework-core**: Fix Model ID attribute not showing up in `invoke_agent` span ([#2061](https://github.com/microsoft/agent-framework/pull/2061))
+- **agent-framework-core**: Fix underlying tool choice bug and enable return to previous Handoff subagent ([#2037](https://github.com/microsoft/agent-framework/pull/2037))
+
 ## [1.0.0b251108] - 2025-11-08

 ### Added
@@ -189,7 +204,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 For more information, see the [announcement blog post](https://devblogs.microsoft.com/foundry/introducing-microsoft-agent-framework-the-open-source-engine-for-agentic-ai-apps/).

-[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251108...HEAD
+[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251111...HEAD
+[1.0.0b251111]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251108...python-1.0.0b251111
 [1.0.0b251108]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251106.post1...python-1.0.0b251108
 [1.0.0b251106.post1]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251106...python-1.0.0b251106.post1
 [1.0.0b251106]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251105...python-1.0.0b251106
@@ -388,6 +388,17 @@ class A2AAgent(BaseAgent):
        if task.artifacts is not None:
            for artifact in task.artifacts:
                messages.append(self._artifact_to_chat_message(artifact))
+        elif task.history is not None and len(task.history) > 0:
+            # Include the last history item as the agent response
+            history_item = task.history[-1]
+            contents = self._a2a_parts_to_contents(history_item.parts)
+            messages.append(
+                ChatMessage(
+                    role=Role.ASSISTANT if history_item.role == A2ARole.agent else Role.USER,
+                    contents=contents,
+                    raw_representation=history_item,
+                )
+            )

        return messages

@@ -4,7 +4,7 @@ description = "A2A integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -10,6 +10,8 @@ pip install agent-framework-ag-ui

 ## Quick Start

+### Server (Host an AI Agent)
+
 ```python
 from fastapi import FastAPI
 from agent_framework import ChatAgent
@@ -23,6 +25,7 @@ agent = ChatAgent(
    chat_client=AzureOpenAIChatClient(
        endpoint="https://your-resource.openai.azure.com/",
        deployment_name="gpt-4o-mini",
+        api_key="your-api-key",
    ),
 )

@@ -33,9 +36,38 @@ add_agent_framework_fastapi_endpoint(app, agent, "/")
 # Run with: uvicorn main:app --reload
 ```

+### Client (Connect to an AG-UI Server)
+
+```python
+import asyncio
+from agent_framework import TextContent
+from agent_framework_ag_ui import AGUIChatClient
+
+async def main():
+    async with AGUIChatClient(endpoint="http://localhost:8000/") as client:
+        # Stream responses
+        async for update in client.get_streaming_response("Hello!"):
+            for content in update.contents:
+                if isinstance(content, TextContent):
+                    print(content.text, end="", flush=True)
+        print()
+
+asyncio.run(main())
+```
+
+The `AGUIChatClient` supports:
+- Streaming and non-streaming responses
+- Hybrid tool execution (client-side + server-side tools)
+- Automatic thread management for conversation continuity
+- Integration with `ChatAgent` for client-side history management
+
 ## Documentation

- **[Getting Started Tutorial](getting_started/)** - Step-by-step guide to building your first AG-UI server and client
+- **[Getting Started Tutorial](getting_started/)** - Step-by-step guide to building AG-UI servers and clients
+  - Server setup with FastAPI
+  - Client examples using `AGUIChatClient`
+  - Hybrid tool execution (client-side + server-side)
+  - Thread management and conversation continuity
 - **[Examples](agent_framework_ag_ui_examples/)** - Complete examples for AG-UI features

 ## Features
@@ -5,6 +5,7 @@
 import importlib.metadata

 from ._agent import AgentFrameworkAgent
+from ._client import AGUIChatClient
 from ._confirmation_strategies import (
    ConfirmationStrategy,
    DefaultConfirmationStrategy,
@@ -13,6 +14,8 @@ from ._confirmation_strategies import (
    TaskPlannerConfirmationStrategy,
 )
 from ._endpoint import add_agent_framework_fastapi_endpoint
+from ._event_converters import AGUIEventConverter
+from ._http_service import AGUIHttpService

 try:
    __version__ = importlib.metadata.version(__name__)
@@ -22,6 +25,9 @@ except importlib.metadata.PackageNotFoundError:
 __all__ = [
    "AgentFrameworkAgent",
    "add_agent_framework_fastapi_endpoint",
+    "AGUIChatClient",
+    "AGUIEventConverter",
+    "AGUIHttpService",
    "ConfirmationStrategy",
    "DefaultConfirmationStrategy",
    "TaskPlannerConfirmationStrategy",
@@ -0,0 +1,407 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""AG-UI Chat Client implementation."""
+
+import json
+import logging
+import uuid
+from collections.abc import AsyncIterable, MutableSequence
+from functools import wraps
+from typing import Any, TypeVar, cast
+
+import httpx
+from agent_framework import (
+    AIFunction,
+    BaseChatClient,
+    ChatMessage,
+    ChatOptions,
+    ChatResponse,
+    ChatResponseUpdate,
+    DataContent,
+    FunctionCallContent,
+)
+from agent_framework._middleware import use_chat_middleware
+from agent_framework._tools import use_function_invocation
+from agent_framework._types import BaseContent, Contents
+from agent_framework.observability import use_observability
+
+from ._event_converters import AGUIEventConverter
+from ._http_service import AGUIHttpService
+from ._message_adapters import agent_framework_messages_to_agui
+from ._utils import convert_tools_to_agui_format
+
+logger: logging.Logger = logging.getLogger(__name__)
+
+
+class ServerFunctionCallContent(BaseContent):
+    """Wrapper for server function calls to prevent client re-execution.
+
+    All function calls from the remote server are server-side executions.
+    This wrapper prevents @use_function_invocation from trying to execute them again.
+    """
+
+    function_call_content: FunctionCallContent
+
+    def __init__(self, function_call_content: FunctionCallContent) -> None:
+        """Initialize with the function call content."""
+        super().__init__(type="server_function_call")
+        self.function_call_content = function_call_content
+
+
+def _unwrap_server_function_call_contents(contents: MutableSequence[Contents | dict[str, Any]]) -> None:
+    """Replace ServerFunctionCallContent instances with their underlying call content."""
+    for idx, content in enumerate(contents):
+        if isinstance(content, ServerFunctionCallContent):
+            contents[idx] = content.function_call_content  # type: ignore[assignment]
+
+
+TBaseChatClient = TypeVar("TBaseChatClient", bound=type[BaseChatClient])
+
+
+def _apply_server_function_call_unwrap(chat_client: TBaseChatClient) -> TBaseChatClient:
+    """Class decorator that unwraps server-side function calls after tool handling."""
+
+    original_get_streaming_response = chat_client.get_streaming_response
+
+    @wraps(original_get_streaming_response)
+    async def streaming_wrapper(self, *args: Any, **kwargs: Any) -> AsyncIterable[ChatResponseUpdate]:
+        async for update in original_get_streaming_response(self, *args, **kwargs):
+            _unwrap_server_function_call_contents(cast(MutableSequence[Contents | dict[str, Any]], update.contents))
+            yield update
+
+    chat_client.get_streaming_response = streaming_wrapper  # type: ignore[assignment]
+
+    original_get_response = chat_client.get_response
+
+    @wraps(original_get_response)
+    async def response_wrapper(self, *args: Any, **kwargs: Any) -> ChatResponse:
+        response = await original_get_response(self, *args, **kwargs)
+        if response.messages:
+            for message in response.messages:
+                _unwrap_server_function_call_contents(
+                    cast(MutableSequence[Contents | dict[str, Any]], message.contents)
+                )
+        return response
+
+    chat_client.get_response = response_wrapper  # type: ignore[assignment]
+    return chat_client
+
+
+@_apply_server_function_call_unwrap
+@use_function_invocation
+@use_observability
+@use_chat_middleware
+class AGUIChatClient(BaseChatClient):
+    """Chat client for communicating with AG-UI compliant servers.
+
+    This client implements the BaseChatClient interface and automatically handles:
+    - Thread ID management for conversation continuity
+    - State synchronization between client and server
+    - Server-Sent Events (SSE) streaming
+    - Event conversion to Agent Framework types
+
+    Important: Message History Management
+        This client sends exactly the messages it receives to the server. It does NOT
+        automatically maintain conversation history. The server must handle history via thread_id.
+
+        For stateless servers: Use ChatAgent wrapper which will send full message history on each
+        request. However, even with ChatAgent, the server must echo back all context for the
+        agent to maintain history across turns.
+
+    Important: Tool Handling (Hybrid Execution - matches .NET)
+        1. Client tool metadata sent to server - LLM knows about both client and server tools
+        2. Server has its own tools that execute server-side
+        3. When LLM calls a client tool, @use_function_invocation executes it locally
+        4. Both client and server tools work together (hybrid pattern)
+
+        The wrapping ChatAgent's @use_function_invocation handles client tool execution
+        automatically when the server's LLM decides to call them.
+
+    Examples:
+        Direct usage (server manages thread history):
+
+        .. code-block:: python
+
+            from agent_framework.ag_ui import AGUIChatClient
+
+            client = AGUIChatClient(endpoint="http://localhost:8888/")
+
+            # First message - thread ID auto-generated
+            response = await client.get_response("Hello!")
+            thread_id = response.additional_properties.get("thread_id")
+
+            # Second message - server retrieves history using thread_id
+            response2 = await client.get_response(
+                "How are you?",
+                metadata={"thread_id": thread_id}
+            )
+
+        Recommended usage with ChatAgent (client manages history):
+
+        .. code-block:: python
+
+            from agent_framework import ChatAgent
+            from agent_framework.ag_ui import AGUIChatClient
+
+            client = AGUIChatClient(endpoint="http://localhost:8888/")
+            agent = ChatAgent(name="assistant", client=client)
+            thread = await agent.get_new_thread()
+
+            # ChatAgent automatically maintains history and sends full context
+            response = await agent.run("Hello!", thread=thread)
+            response2 = await agent.run("How are you?", thread=thread)
+
+        Streaming usage:
+
+        .. code-block:: python
+
+            async for update in client.get_streaming_response("Tell me a story"):
+                if update.contents:
+                    for content in update.contents:
+                        if hasattr(content, "text"):
+                            print(content.text, end="", flush=True)
+
+        Context manager:
+
+        .. code-block:: python
+
+            async with AGUIChatClient(endpoint="http://localhost:8888/") as client:
+                response = await client.get_response("Hello!")
+                print(response.messages[0].text)
+    """
+
+    OTEL_PROVIDER_NAME = "agui"
+
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        http_client: httpx.AsyncClient | None = None,
+        timeout: float = 60.0,
+        additional_properties: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the AG-UI chat client.
+
+        Args:
+            endpoint: The AG-UI server endpoint URL (e.g., "http://localhost:8888/")
+            http_client: Optional httpx.AsyncClient instance. If None, one will be created.
+            timeout: Request timeout in seconds (default: 60.0)
+            additional_properties: Additional properties to store
+            **kwargs: Additional arguments passed to BaseChatClient
+        """
+        super().__init__(additional_properties=additional_properties, **kwargs)
+        self._http_service = AGUIHttpService(
+            endpoint=endpoint,
+            http_client=http_client,
+            timeout=timeout,
+        )
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._http_service.close()
+
+    async def __aenter__(self) -> "AGUIChatClient":
+        """Enter async context manager."""
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        """Exit async context manager."""
+        await self.close()
+
+    def _register_server_tool_placeholder(self, tool_name: str) -> None:
+        """Register a declaration-only placeholder so function invocation skips execution."""
+
+        config = getattr(self, "function_invocation_configuration", None)
+        if not config:
+            return
+        if any(getattr(tool, "name", None) == tool_name for tool in config.additional_tools):
+            return
+
+        placeholder: AIFunction[Any, Any] = AIFunction(
+            name=tool_name,
+            description="Server-managed tool placeholder (AG-UI)",
+            func=None,
+        )
+        config.additional_tools = list(config.additional_tools) + [placeholder]
+        registered: set[str] = getattr(self, "_registered_server_tools", set())
+        registered.add(tool_name)
+        self._registered_server_tools = registered  # type: ignore[attr-defined]
+        from agent_framework._logging import get_logger
+
+        logger = get_logger()
+        logger.debug(f"[AGUIChatClient] Registered server placeholder: {tool_name}")
+
+    def _extract_state_from_messages(
+        self, messages: MutableSequence[ChatMessage]
+    ) -> tuple[list[ChatMessage], dict[str, Any] | None]:
+        """Extract state from last message if present.
+
+        Args:
+            messages: List of chat messages
+
+        Returns:
+            Tuple of (messages_without_state, state_dict)
+        """
+        if not messages:
+            return list(messages), None
+
+        last_message = messages[-1]
+
+        for content in last_message.contents:
+            if isinstance(content, DataContent) and content.media_type == "application/json":
+                try:
+                    uri = content.uri
+                    if uri.startswith("data:application/json;base64,"):
+                        import base64
+
+                        encoded_data = uri.split(",", 1)[1]
+                        decoded_bytes = base64.b64decode(encoded_data)
+                        state = json.loads(decoded_bytes.decode("utf-8"))
+
+                        messages_without_state = list(messages[:-1]) if len(messages) > 1 else []
+                        return messages_without_state, state
+                except (json.JSONDecodeError, ValueError, KeyError) as e:
+                    from agent_framework._logging import get_logger
+
+                    logger = get_logger()
+                    logger.warning(f"Failed to extract state from message: {e}")
+
+        return list(messages), None
+
+    def _convert_messages_to_agui_format(self, messages: list[ChatMessage]) -> list[dict[str, Any]]:
+        """Convert Agent Framework messages to AG-UI format.
+
+        Args:
+            messages: List of ChatMessage objects
+
+        Returns:
+            List of AG-UI formatted message dictionaries
+        """
+        return agent_framework_messages_to_agui(messages)
+
+    def _get_thread_id(self, chat_options: ChatOptions) -> str:
+        """Get or generate thread ID from chat options.
+
+        Args:
+            chat_options: Chat options containing metadata
+
+        Returns:
+            Thread ID string
+        """
+        thread_id = None
+        if chat_options.metadata:
+            thread_id = chat_options.metadata.get("thread_id")
+
+        if not thread_id:
+            thread_id = f"thread_{uuid.uuid4().hex}"
+
+        return thread_id
+
+    async def _inner_get_response(
+        self,
+        *,
+        messages: MutableSequence[ChatMessage],
+        chat_options: ChatOptions,
+        **kwargs: Any,
+    ) -> ChatResponse:
+        """Internal method to get non-streaming response.
+
+        Keyword Args:
+            messages: List of chat messages
+            chat_options: Chat options for the request
+            **kwargs: Additional keyword arguments
+
+        Returns:
+            ChatResponse object
+        """
+        return await ChatResponse.from_chat_response_generator(
+            self._inner_get_streaming_response(
+                messages=messages,
+                chat_options=chat_options,
+                **kwargs,
+            )
+        )
+
+    async def _inner_get_streaming_response(
+        self,
+        *,
+        messages: MutableSequence[ChatMessage],
+        chat_options: ChatOptions,
+        **kwargs: Any,
+    ) -> AsyncIterable[ChatResponseUpdate]:
+        """Internal method to get streaming response.
+
+        Keyword Args:
+            messages: List of chat messages
+            chat_options: Chat options for the request
+            **kwargs: Additional keyword arguments
+
+        Yields:
+            ChatResponseUpdate objects
+        """
+        messages_to_send, state = self._extract_state_from_messages(messages)
+
+        thread_id = self._get_thread_id(chat_options)
+        run_id = f"run_{uuid.uuid4().hex}"
+
+        agui_messages = self._convert_messages_to_agui_format(messages_to_send)
+
+        # Send client tools to server so LLM knows about them
+        # Client tools execute via ChatAgent's @use_function_invocation wrapper
+        agui_tools = convert_tools_to_agui_format(chat_options.tools)
+
+        # Build set of client tool names (matches .NET clientToolSet)
+        # Used to distinguish client vs server tools in response stream
+        client_tool_set: set[str] = set()
+        if chat_options.tools:
+            for tool in chat_options.tools:
+                if hasattr(tool, "name"):
+                    client_tool_set.add(tool.name)  # type: ignore[arg-type]
+        self._last_client_tool_set = client_tool_set  # type: ignore[attr-defined]
+
+        logger.debug(
+            "[AGUIChatClient] Preparing request",
+            extra={
+                "thread_id": thread_id,
+                "run_id": run_id,
+                "client_tools": list(client_tool_set),
+                "messages": [msg.text for msg in messages_to_send if msg.text],
+            },
+        )
+        logger.debug(f"[AGUIChatClient] Client tool set: {client_tool_set}")
+
+        converter = AGUIEventConverter()
+
+        async for event in self._http_service.post_run(
+            thread_id=thread_id,
+            run_id=run_id,
+            messages=agui_messages,
+            state=state,
+            tools=agui_tools,
+        ):
+            logger.debug(f"[AGUIChatClient] Raw AG-UI event: {event}")
+            update = converter.convert_event(event)
+            if update is not None:
+                logger.debug(
+                    "[AGUIChatClient] Converted update",
+                    extra={"role": update.role, "contents": [type(c).__name__ for c in update.contents]},
+                )
+                # Distinguish client vs server tools
+                for i, content in enumerate(update.contents):
+                    if isinstance(content, FunctionCallContent):
+                        logger.debug(
+                            f"[AGUIChatClient] Function call: {content.name}, in client_tool_set: {content.name in client_tool_set}"
+                        )
+                        if content.name in client_tool_set:
+                            # Client tool - let @use_function_invocation execute it
+                            if not content.additional_properties:
+                                content.additional_properties = {}
+                            content.additional_properties["agui_thread_id"] = thread_id
+                        else:
+                            # Server tool - wrap so @use_function_invocation ignores it
+                            logger.debug(f"[AGUIChatClient] Wrapping server tool: {content.name}")
+                            self._register_server_tool_placeholder(content.name)
+                            update.contents[i] = ServerFunctionCallContent(content)  # type: ignore
+
+                yield update
@@ -0,0 +1,209 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Event converter for AG-UI protocol events to Agent Framework types."""
+
+from typing import Any
+
+from agent_framework import (
+    ChatResponseUpdate,
+    ErrorContent,
+    FinishReason,
+    FunctionCallContent,
+    FunctionResultContent,
+    Role,
+    TextContent,
+)
+
+
+class AGUIEventConverter:
+    """Converter for AG-UI events to Agent Framework types.
+
+    Handles conversion of AG-UI protocol events to ChatResponseUpdate objects
+    while maintaining state, aggregating content, and tracking metadata.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the converter with fresh state."""
+        self.current_message_id: str | None = None
+        self.current_tool_call_id: str | None = None
+        self.current_tool_name: str | None = None
+        self.accumulated_tool_args: str = ""
+        self.thread_id: str | None = None
+        self.run_id: str | None = None
+
+    def convert_event(self, event: dict[str, Any]) -> ChatResponseUpdate | None:
+        """Convert a single AG-UI event to ChatResponseUpdate.
+
+        Args:
+            event: AG-UI event dictionary
+
+        Returns:
+            ChatResponseUpdate if event produces content, None otherwise
+
+        Examples:
+            RUN_STARTED event:
+
+            .. code-block:: python
+
+                converter = AGUIEventConverter()
+                event = {"type": "RUN_STARTED", "threadId": "t1", "runId": "r1"}
+                update = converter.convert_event(event)
+                assert update.additional_properties["thread_id"] == "t1"
+
+            TEXT_MESSAGE_CONTENT event:
+
+            .. code-block:: python
+
+                event = {"type": "TEXT_MESSAGE_CONTENT", "messageId": "m1", "delta": "Hello"}
+                update = converter.convert_event(event)
+                assert update.contents[0].text == "Hello"
+        """
+        event_type = event.get("type", "")
+
+        if event_type == "RUN_STARTED":
+            return self._handle_run_started(event)
+        elif event_type == "TEXT_MESSAGE_START":
+            return self._handle_text_message_start(event)
+        elif event_type == "TEXT_MESSAGE_CONTENT":
+            return self._handle_text_message_content(event)
+        elif event_type == "TEXT_MESSAGE_END":
+            return self._handle_text_message_end(event)
+        elif event_type == "TOOL_CALL_START":
+            return self._handle_tool_call_start(event)
+        elif event_type == "TOOL_CALL_ARGS":
+            return self._handle_tool_call_args(event)
+        elif event_type == "TOOL_CALL_END":
+            return self._handle_tool_call_end(event)
+        elif event_type == "TOOL_CALL_RESULT":
+            return self._handle_tool_call_result(event)
+        elif event_type == "RUN_FINISHED":
+            return self._handle_run_finished(event)
+        elif event_type == "RUN_ERROR":
+            return self._handle_run_error(event)
+
+        return None
+
+    def _handle_run_started(self, event: dict[str, Any]) -> ChatResponseUpdate:
+        """Handle RUN_STARTED event."""
+        self.thread_id = event.get("threadId")
+        self.run_id = event.get("runId")
+
+        return ChatResponseUpdate(
+            role=Role.ASSISTANT,
+            contents=[],
+            additional_properties={
+                "thread_id": self.thread_id,
+                "run_id": self.run_id,
+            },
+        )
+
+    def _handle_text_message_start(self, event: dict[str, Any]) -> ChatResponseUpdate | None:
+        """Handle TEXT_MESSAGE_START event."""
+        self.current_message_id = event.get("messageId")
+        return ChatResponseUpdate(
+            role=Role.ASSISTANT,
+            message_id=self.current_message_id,
+            contents=[],
+        )
+
+    def _handle_text_message_content(self, event: dict[str, Any]) -> ChatResponseUpdate:
+        """Handle TEXT_MESSAGE_CONTENT event."""
+        message_id = event.get("messageId")
+        delta = event.get("delta", "")
+
+        if message_id != self.current_message_id:
+            self.current_message_id = message_id
+
+        return ChatResponseUpdate(
+            role=Role.ASSISTANT,
+            message_id=self.current_message_id,
+            contents=[TextContent(text=delta)],
+        )
+
+    def _handle_text_message_end(self, event: dict[str, Any]) -> ChatResponseUpdate | None:
+        """Handle TEXT_MESSAGE_END event."""
+        return None
+
+    def _handle_tool_call_start(self, event: dict[str, Any]) -> ChatResponseUpdate:
+        """Handle TOOL_CALL_START event."""
+        self.current_tool_call_id = event.get("toolCallId")
+        self.current_tool_name = event.get("toolName") or event.get("toolCallName") or event.get("tool_call_name")
+        self.accumulated_tool_args = ""
+
+        return ChatResponseUpdate(
+            role=Role.ASSISTANT,
+            contents=[
+                FunctionCallContent(
+                    call_id=self.current_tool_call_id or "",
+                    name=self.current_tool_name or "",
+                    arguments="",
+                )
+            ],
+        )
+
+    def _handle_tool_call_args(self, event: dict[str, Any]) -> ChatResponseUpdate:
+        """Handle TOOL_CALL_ARGS event."""
+        delta = event.get("delta", "")
+        self.accumulated_tool_args += delta
+
+        return ChatResponseUpdate(
+            role=Role.ASSISTANT,
+            contents=[
+                FunctionCallContent(
+                    call_id=self.current_tool_call_id or "",
+                    name=self.current_tool_name or "",
+                    arguments=delta,
+                )
+            ],
+        )
+
+    def _handle_tool_call_end(self, event: dict[str, Any]) -> ChatResponseUpdate | None:
+        """Handle TOOL_CALL_END event."""
+        self.accumulated_tool_args = ""
+        return None
+
+    def _handle_tool_call_result(self, event: dict[str, Any]) -> ChatResponseUpdate:
+        """Handle TOOL_CALL_RESULT event."""
+        tool_call_id = event.get("toolCallId", "")
+        result = event.get("result") if event.get("result") is not None else event.get("content")
+
+        return ChatResponseUpdate(
+            role=Role.TOOL,
+            contents=[
+                FunctionResultContent(
+                    call_id=tool_call_id,
+                    result=result,
+                )
+            ],
+        )
+
+    def _handle_run_finished(self, event: dict[str, Any]) -> ChatResponseUpdate:
+        """Handle RUN_FINISHED event."""
+        return ChatResponseUpdate(
+            role=Role.ASSISTANT,
+            finish_reason=FinishReason.STOP,
+            contents=[],
+            additional_properties={
+                "thread_id": self.thread_id,
+                "run_id": self.run_id,
+            },
+        )
+
+    def _handle_run_error(self, event: dict[str, Any]) -> ChatResponseUpdate:
+        """Handle RUN_ERROR event."""
+        error_message = event.get("message", "Unknown error")
+
+        return ChatResponseUpdate(
+            role=Role.ASSISTANT,
+            finish_reason=FinishReason.CONTENT_FILTER,
+            contents=[
+                ErrorContent(
+                    message=error_message,
+                    error_code="RUN_ERROR",
+                )
+            ],
+            additional_properties={
+                "thread_id": self.thread_id,
+                "run_id": self.run_id,
+            },
+        )
@@ -107,7 +107,7 @@ class AgentFrameworkEventBridge:
                # Skip text content if we're about to emit confirm_changes
                # The summary should only appear after user confirms
                if self.should_stop_after_confirm:
-                    logger.debug("  >>> Skipping text content - waiting for confirm_changes response")
+                    logger.debug("Skipping text content - waiting for confirm_changes response")
                    # Save the summary text to show after confirmation
                    self.suppressed_summary += content.text
                    continue
@@ -156,7 +156,7 @@ class AgentFrameworkEventBridge:
                        tool_call_name=content.name,
                        parent_message_id=self.current_message_id,
                    )
-                    logger.info(f"  >>> Emitting ToolCallStartEvent with name='{content.name}', id='{tool_call_id}'")
+                    logger.info(f"Emitting ToolCallStartEvent with name='{content.name}', id='{tool_call_id}'")
                    events.append(tool_start_event)

                    # Track tool call for MessagesSnapshotEvent
@@ -186,7 +186,7 @@ class AgentFrameworkEventBridge:
                        # If it's a dict, convert to JSON
                        delta_str = json.dumps(content.arguments)

-                    logger.info(f"  >>> Emitting ToolCallArgsEvent with delta: {delta_str!r}..., id='{tool_call_id}'")
+                    logger.info(f"Emitting ToolCallArgsEvent with delta: {delta_str!r}..., id='{tool_call_id}'")
                    args_event = ToolCallArgsEvent(
                        tool_call_id=tool_call_id,
                        delta=delta_str,
@@ -211,7 +211,7 @@ class AgentFrameworkEventBridge:
                            self.streaming_tool_args += json.dumps(content.arguments)

                        logger.debug(
-                            f"  >>> Predictive state: accumulated {len(self.streaming_tool_args)} chars for tool '{self.current_tool_call_name}'"
+                            f"Predictive state: accumulated {len(self.streaming_tool_args)} chars for tool '{self.current_tool_call_name}'"
                        )

                        # Try to parse accumulated arguments (may be incomplete JSON)
@@ -262,11 +262,11 @@ class AgentFrameworkEventBridge:
                                                    else str(partial_value)
                                                )
                                                logger.info(
-                                                    f"  >>> StateDeltaEvent #{self.state_delta_count} for '{state_key}': "
+                                                    f"StateDeltaEvent #{self.state_delta_count} for '{state_key}': "
                                                    f"op=replace, path=/{state_key}, value={value_preview}"
                                                )
                                            elif self.state_delta_count % 100 == 0:
-                                                logger.info(f"  >>> StateDeltaEvent #{self.state_delta_count} emitted")
+                                                logger.info(f"StateDeltaEvent #{self.state_delta_count} emitted")

                                            events.append(state_delta_event)
                                            self.last_emitted_state[state_key] = partial_value
@@ -312,11 +312,11 @@ class AgentFrameworkEventBridge:
                                                else str(state_value)
                                            )
                                            logger.info(
-                                                f"  >>> StateDeltaEvent #{self.state_delta_count} for '{state_key}': "
+                                                f"StateDeltaEvent #{self.state_delta_count} for '{state_key}': "
                                                f"op=replace, path=/{state_key}, value={value_preview}"
                                            )
                                        elif self.state_delta_count % 100 == 0:  # Also log every 100th
-                                            logger.info(f"  >>> StateDeltaEvent #{self.state_delta_count} emitted")
+                                            logger.info(f"StateDeltaEvent #{self.state_delta_count} emitted")

                                        events.append(state_delta_event)

@@ -360,7 +360,7 @@ class AgentFrameworkEventBridge:
                                        ],
                                    )
                                    logger.info(
-                                        f"  >>> Emitting StateDeltaEvent for key '{state_key}', value type: {type(state_value)}"
+                                        f"Emitting StateDeltaEvent for key '{state_key}', value type: {type(state_value)}"
                                    )
                                    events.append(state_delta_event)

@@ -376,13 +376,13 @@ class AgentFrameworkEventBridge:
                    end_event = ToolCallEndEvent(
                        tool_call_id=content.call_id,
                    )
-                    logger.info(f"  >>> Emitting ToolCallEndEvent for completed tool call '{content.call_id}'")
+                    logger.info(f"Emitting ToolCallEndEvent for completed tool call '{content.call_id}'")
                    events.append(end_event)

                    # Log total StateDeltaEvent count for this tool call
                    if self.state_delta_count > 0:
                        logger.info(
-                            f"  >>> Tool call '{content.call_id}' complete: emitted {self.state_delta_count} StateDeltaEvents total"
+                            f"Tool call '{content.call_id}' complete: emitted {self.state_delta_count} StateDeltaEvents total"
                        )

                    # Reset streaming accumulator and counter for next tool call
@@ -410,11 +410,13 @@ class AgentFrameworkEventBridge:
                events.append(result_event)

                # Track tool result for MessagesSnapshotEvent
+                # AG-UI protocol expects: { role: "tool", toolCallId: ..., content: ... }
+                # Use camelCase for Pydantic's alias_generator=to_camel
                self.tool_results.append(
                    {
                        "id": result_message_id,
                        "role": "tool",
-                        "tool_call_id": content.call_id,
+                        "toolCallId": content.call_id,
                        "content": result_content,
                    }
                )
@@ -422,6 +424,9 @@ class AgentFrameworkEventBridge:
                # Emit MessagesSnapshotEvent with the complete conversation including tool calls and results
                # This is required for CopilotKit's useCopilotAction to detect tool result
                if self.pending_tool_calls and self.tool_results:
+                    # Import message adapter
+                    from ._message_adapters import agent_framework_messages_to_agui
+
                    # Build assistant message with tool_calls
                    assistant_message = {
                        "id": generate_event_id(),
@@ -429,14 +434,19 @@ class AgentFrameworkEventBridge:
                        "tool_calls": self.pending_tool_calls.copy(),  # Copy the accumulated tool calls
                    }

+                    # Convert Agent Framework messages to AG-UI format (adds required 'id' field)
+                    converted_input_messages = agent_framework_messages_to_agui(self.input_messages)
+
                    # Build complete messages array: input messages + assistant message + tool results
-                    all_messages = list(self.input_messages) + [assistant_message] + self.tool_results.copy()
+                    all_messages = converted_input_messages + [assistant_message] + self.tool_results.copy()

                    # Emit MessagesSnapshotEvent using the proper event type
+                    # Note: messages are dict[str, Any] but Pydantic will validate them as Message types
                    messages_snapshot_event = MessagesSnapshotEvent(
-                        type=EventType.MESSAGES_SNAPSHOT, messages=all_messages
+                        type=EventType.MESSAGES_SNAPSHOT,
+                        messages=all_messages,  # type: ignore[arg-type]
                    )
-                    logger.info(f"  >>> Emitting MessagesSnapshotEvent with {len(all_messages)} messages")
+                    logger.info(f"Emitting MessagesSnapshotEvent with {len(all_messages)} messages")
                    events.append(messages_snapshot_event)

                # After tool execution, emit StateSnapshotEvent if we have pending state updates
@@ -466,7 +476,7 @@ class AgentFrameworkEventBridge:
                    # If so, emit a confirm_changes tool call for the UI modal
                    tool_was_predictive = False
                    logger.debug(
-                        f"  >>> Checking predictive state: current_tool='{self.current_tool_call_name}', "
+                        f"Checking predictive state: current_tool='{self.current_tool_call_name}', "
                        f"predict_config={list(self.predict_state_config.keys()) if self.predict_state_config else 'None'}"
                    )
                    for state_key, config in self.predict_state_config.items():
@@ -474,7 +484,7 @@ class AgentFrameworkEventBridge:
                        # We need to match against self.current_tool_call_name
                        if self.current_tool_call_name and config["tool"] == self.current_tool_call_name:
                            logger.info(
-                                f"  >>> Tool '{self.current_tool_call_name}' matches predictive config for state key '{state_key}'"
+                                f"Tool '{self.current_tool_call_name}' matches predictive config for state key '{state_key}'"
                            )
                            tool_was_predictive = True
                            break
@@ -483,7 +493,7 @@ class AgentFrameworkEventBridge:
                        # Emit confirm_changes tool call sequence
                        confirm_call_id = generate_event_id()

-                        logger.info("  >>> Emitting confirm_changes tool call for predictive update")
+                        logger.info("Emitting confirm_changes tool call for predictive update")

                        # Track confirm_changes tool call for MessagesSnapshotEvent (so it persists after RUN_FINISHED)
                        self.pending_tool_calls.append(
@@ -518,6 +528,9 @@ class AgentFrameworkEventBridge:
                        events.append(confirm_end)

                        # Emit MessagesSnapshotEvent so confirm_changes persists after RUN_FINISHED
+                        # Import message adapter
+                        from ._message_adapters import agent_framework_messages_to_agui
+
                        # Build assistant message with pending confirm_changes tool call
                        assistant_message = {
                            "id": generate_event_id(),
@@ -525,23 +538,28 @@ class AgentFrameworkEventBridge:
                            "tool_calls": self.pending_tool_calls.copy(),  # Includes confirm_changes
                        }

+                        # Convert Agent Framework messages to AG-UI format (adds required 'id' field)
+                        converted_input_messages = agent_framework_messages_to_agui(self.input_messages)
+
                        # Build complete messages array: input messages + assistant message + any tool results
-                        all_messages = list(self.input_messages) + [assistant_message] + self.tool_results.copy()
+                        all_messages = converted_input_messages + [assistant_message] + self.tool_results.copy()

                        # Emit MessagesSnapshotEvent
+                        # Note: messages are dict[str, Any] but Pydantic will validate them as Message types
                        messages_snapshot_event = MessagesSnapshotEvent(
-                            type=EventType.MESSAGES_SNAPSHOT, messages=all_messages
+                            type=EventType.MESSAGES_SNAPSHOT,
+                            messages=all_messages,  # type: ignore[arg-type]
                        )
                        logger.info(
-                            f"  >>> Emitting MessagesSnapshotEvent for confirm_changes with {len(all_messages)} messages"
+                            f"Emitting MessagesSnapshotEvent for confirm_changes with {len(all_messages)} messages"
                        )
                        events.append(messages_snapshot_event)

                        # Set flag to stop the run after this - we're waiting for user response
                        self.should_stop_after_confirm = True
-                        logger.info("  >>> Set flag to stop run after confirm_changes")
+                        logger.info("Set flag to stop run after confirm_changes")
                    elif tool_was_predictive:
-                        logger.info("  >>> Skipping confirm_changes - require_confirmation is False")
+                        logger.info("Skipping confirm_changes - require_confirmation is False")

                    # Clear pending updates and reset tool name tracker
                    self.pending_state_updates.clear()
@@ -580,7 +598,7 @@ class AgentFrameworkEventBridge:
                            # Update current state
                            self.current_state[state_key] = state_value
                            logger.info(
-                                f"  >>> Emitting StateSnapshotEvent for key '{state_key}', value type: {type(state_value)}"
+                                f"Emitting StateSnapshotEvent for key '{state_key}', value type: {type(state_value)}"
                            )

                            # Emit state snapshot
@@ -596,7 +614,7 @@ class AgentFrameworkEventBridge:
                        tool_call_id=content.function_call.call_id,
                    )
                    logger.info(
-                        f"  >>> Emitting ToolCallEndEvent for approval-required tool '{content.function_call.call_id}'"
+                        f"Emitting ToolCallEndEvent for approval-required tool '{content.function_call.call_id}'"
                    )
                    events.append(end_event)

@@ -615,7 +633,7 @@ class AgentFrameworkEventBridge:
                        },
                    },
                )
-                logger.info(f"  >>> Emitting function_approval_request custom event for '{content.function_call.name}'")
+                logger.info(f"Emitting function_approval_request custom event for '{content.function_call.name}'")
                events.append(approval_event)

        return events
@@ -0,0 +1,157 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""HTTP service for AG-UI protocol communication."""
+
+import json
+import logging
+from collections.abc import AsyncIterable
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class AGUIHttpService:
+    """HTTP service for AG-UI protocol communication.
+
+    Handles HTTP POST requests and Server-Sent Events (SSE) stream parsing
+    for the AG-UI protocol.
+
+    Examples:
+        Basic usage:
+
+        .. code-block:: python
+
+            service = AGUIHttpService("http://localhost:8888/")
+            async for event in service.post_run(
+                thread_id="thread_123",
+                run_id="run_456",
+                messages=[{"role": "user", "content": "Hello"}]
+            ):
+                print(event["type"])
+
+        With context manager:
+
+        .. code-block:: python
+
+            async with AGUIHttpService("http://localhost:8888/") as service:
+                async for event in service.post_run(...):
+                    print(event)
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        http_client: httpx.AsyncClient | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        """Initialize the HTTP service.
+
+        Args:
+            endpoint: AG-UI server endpoint URL (e.g., "http://localhost:8888/")
+            http_client: Optional httpx AsyncClient. If None, creates a new one.
+            timeout: Request timeout in seconds (default: 60.0)
+        """
+        self.endpoint = endpoint.rstrip("/")
+        self._owns_client = http_client is None
+        self.http_client = http_client or httpx.AsyncClient(timeout=timeout)
+
+    async def post_run(
+        self,
+        thread_id: str,
+        run_id: str,
+        messages: list[dict[str, Any]],
+        state: dict[str, Any] | None = None,
+        tools: list[dict[str, Any]] | None = None,
+    ) -> AsyncIterable[dict[str, Any]]:
+        """Post a run request and stream AG-UI events.
+
+        Args:
+            thread_id: Thread identifier for conversation continuity
+            run_id: Unique run identifier
+            messages: List of messages in AG-UI format
+            state: Optional state object to send to server
+            tools: Optional list of tools available to the agent
+
+        Yields:
+            AG-UI event dictionaries parsed from SSE stream
+
+        Raises:
+            httpx.HTTPStatusError: If the HTTP request fails
+            ValueError: If SSE parsing encounters invalid data
+
+        Examples:
+            .. code-block:: python
+
+                service = AGUIHttpService("http://localhost:8888/")
+                async for event in service.post_run(
+                    thread_id="thread_abc",
+                    run_id="run_123",
+                    messages=[{"role": "user", "content": "Hello"}],
+                    state={"user_context": {"name": "Alice"}}
+                ):
+                    if event["type"] == "TEXT_MESSAGE_CONTENT":
+                        print(event["delta"])
+        """
+        # Build request payload
+        request_data: dict[str, Any] = {
+            "thread_id": thread_id,
+            "run_id": run_id,
+            "messages": messages,
+        }
+
+        if state is not None:
+            request_data["state"] = state
+
+        if tools is not None:
+            request_data["tools"] = tools
+
+        logger.debug(
+            f"Posting run to {self.endpoint}: thread_id={thread_id}, run_id={run_id}, "
+            f"messages={len(messages)}, has_state={state is not None}, has_tools={tools is not None}"
+        )
+
+        # Stream the response using SSE
+        async with self.http_client.stream(
+            "POST",
+            self.endpoint,
+            json=request_data,
+            headers={"Accept": "text/event-stream"},
+        ) as response:
+            try:
+                response.raise_for_status()
+            except httpx.HTTPStatusError as e:
+                logger.error(f"HTTP request failed: {e.response.status_code} - {e.response.text}")
+                raise
+
+            async for line in response.aiter_lines():
+                # Parse Server-Sent Events format
+                if line.startswith("data: "):
+                    data = line[6:]  # Remove "data: " prefix
+                    try:
+                        event = json.loads(data)
+                        logger.debug(f"Received event: {event.get('type', 'UNKNOWN')}")
+                        yield event
+                    except json.JSONDecodeError as e:
+                        logger.warning(f"Failed to parse SSE data: {data}. Error: {e}")
+                        # Continue processing other events instead of failing
+                        continue
+
+    async def close(self) -> None:
+        """Close the HTTP client if owned by this service.
+
+        Only closes the client if it was created by this service instance.
+        If an external client was provided, it remains the caller's
+        responsibility to close it.
+        """
+        if self._owns_client and self.http_client:
+            await self.http_client.aclose()
+
+    async def __aenter__(self) -> "AGUIHttpService":
+        """Enter async context manager."""
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        """Exit async context manager and clean up resources."""
+        await self.close()
@@ -2,12 +2,13 @@

 """Message format conversion between AG-UI and Agent Framework."""

-from typing import Any
+from typing import Any, cast

 from agent_framework import (
    ChatMessage,
    FunctionApprovalResponseContent,
    FunctionCallContent,
+    FunctionResultContent,
    Role,
    TextContent,
 )
@@ -46,7 +47,7 @@ def agui_messages_to_agent_framework(messages: list[dict[str, Any]]) -> list[Cha
            result_content = msg.get("result", msg.get("content", ""))

            chat_msg = ChatMessage(
-                role=Role.ASSISTANT,  # Tool results are assistant messages
+                role=Role.TOOL,  # Tool results must be tool role
                contents=[FunctionResultContent(call_id=tool_call_id, result=result_content)],
            )

@@ -56,6 +57,42 @@ def agui_messages_to_agent_framework(messages: list[dict[str, Any]]) -> list[Cha
            result.append(chat_msg)
            continue

+        # If assistant message includes tool calls, convert to FunctionCallContent(s)
+        tool_calls = msg.get("tool_calls") or msg.get("toolCalls")
+        if tool_calls:
+            contents: list[Any] = []
+            # Include any assistant text content if present
+            content_text = msg.get("content")
+            if isinstance(content_text, str) and content_text:
+                contents.append(TextContent(text=content_text))
+            # Convert each tool call entry
+            for tc in tool_calls:
+                if not isinstance(tc, dict):
+                    continue
+                # Cast to typed dict for proper type inference
+                tc_dict = cast(dict[str, Any], tc)
+                tc_type = tc_dict.get("type")
+                if tc_type == "function":
+                    func_data = tc_dict.get("function", {})
+                    func_dict = cast(dict[str, Any], func_data) if isinstance(func_data, dict) else {}
+
+                    call_id = str(tc_dict.get("id", ""))
+                    name = str(func_dict.get("name", ""))
+                    arguments = func_dict.get("arguments")
+
+                    contents.append(
+                        FunctionCallContent(
+                            call_id=call_id,
+                            name=name,
+                            arguments=arguments,
+                        )
+                    )
+            chat_msg = ChatMessage(role=Role.ASSISTANT, contents=contents)
+            if "id" in msg:
+                chat_msg.message_id = msg["id"]
+            result.append(chat_msg)
+            continue
+
        role_str = msg.get("role", "user")

        # Handle tool result messages (with role="tool")
@@ -78,11 +115,11 @@ def agui_messages_to_agent_framework(messages: list[dict[str, Any]]) -> list[Cha

            # Backend tool results have non-empty content WITHOUT "accepted" field
            if tool_call_id and result_content and not is_approval:
-                # Backend tool execution - convert to FunctionResultContent
+                # Tool execution result - convert to FunctionResultContent with correct role
                from agent_framework import FunctionResultContent

                chat_msg = ChatMessage(
-                    role=Role.ASSISTANT,  # Tool results are assistant messages
+                    role=Role.TOOL,
                    contents=[FunctionResultContent(call_id=tool_call_id, result=result_content)],
                )

@@ -97,9 +134,8 @@ def agui_messages_to_agent_framework(messages: list[dict[str, Any]]) -> list[Cha
                chat_msg = ChatMessage(
                    role=Role.USER,  # Approval responses are user messages
                    contents=[TextContent(text=content)],
+                    additional_properties={"is_tool_result": True, "tool_call_id": msg.get("toolCallId", "")},
                )
-                # Mark this as a tool result so we can detect it later
-                chat_msg.metadata = {"is_tool_result": True, "tool_call_id": msg.get("toolCallId", "")}  # type: ignore[attr-defined]

                if "id" in msg:
                    chat_msg.message_id = msg["id"]
@@ -112,7 +148,7 @@ def agui_messages_to_agent_framework(messages: list[dict[str, Any]]) -> list[Cha
        # Check if this message contains function approvals
        if "function_approvals" in msg and msg["function_approvals"]:
            # Convert function approvals to FunctionApprovalResponseContent
-            contents: list[Any] = []
+            approval_contents: list[Any] = []
            for approval in msg["function_approvals"]:
                # Create FunctionCallContent with the modified arguments
                func_call = FunctionCallContent(
@@ -127,9 +163,9 @@ def agui_messages_to_agent_framework(messages: list[dict[str, Any]]) -> list[Cha
                    id=approval.get("id", ""),
                    function_call=func_call,
                )
-                contents.append(approval_response)
+                approval_contents.append(approval_response)

-            chat_msg = ChatMessage(role=role, contents=contents)  # type: ignore[arg-type]
+            chat_msg = ChatMessage(role=role, contents=approval_contents)  # type: ignore[arg-type]
        else:
            # Regular text message
            content = msg.get("content", "")
@@ -146,21 +182,44 @@ def agui_messages_to_agent_framework(messages: list[dict[str, Any]]) -> list[Cha
    return result


-def agent_framework_messages_to_agui(messages: list[ChatMessage]) -> list[dict[str, Any]]:
+def agent_framework_messages_to_agui(messages: list[ChatMessage] | list[dict[str, Any]]) -> list[dict[str, Any]]:
    """Convert Agent Framework messages to AG-UI format.

    Args:
-        messages: List of Agent Framework ChatMessage objects
+        messages: List of Agent Framework ChatMessage objects or AG-UI dicts (already converted)

    Returns:
        List of AG-UI message dictionaries
    """
+    from ._utils import generate_event_id
+
    result: list[dict[str, Any]] = []
    for msg in messages:
+        # If already a dict (AG-UI format), ensure it has an ID and normalize keys for Pydantic
+        if isinstance(msg, dict):
+            # Always work on a copy to avoid mutating input
+            normalized_msg = msg.copy()
+            # Ensure ID exists
+            if "id" not in normalized_msg:
+                normalized_msg["id"] = generate_event_id()
+            # Normalize tool_call_id to toolCallId for Pydantic's alias_generator=to_camel
+            if normalized_msg.get("role") == "tool":
+                if "tool_call_id" in normalized_msg:
+                    normalized_msg["toolCallId"] = normalized_msg["tool_call_id"]
+                    del normalized_msg["tool_call_id"]
+                elif "toolCallId" not in normalized_msg:
+                    # Tool message missing toolCallId - add empty string to satisfy schema
+                    normalized_msg["toolCallId"] = ""
+            # Always append the normalized copy, not the original
+            result.append(normalized_msg)
+            continue
+
+        # Convert ChatMessage to AG-UI format
        role = _FRAMEWORK_TO_AGUI_ROLE.get(msg.role, "user")

        content_text = ""
        tool_calls: list[dict[str, Any]] = []
+        tool_result_call_id: str | None = None

        for content in msg.contents:
            if isinstance(content, TextContent):
@@ -176,18 +235,32 @@ def agent_framework_messages_to_agui(messages: list[ChatMessage]) -> list[dict[s
                        },
                    }
                )
+            elif isinstance(content, FunctionResultContent):
+                # Tool result content - extract call_id and result
+                tool_result_call_id = content.call_id
+                # Serialize result to string
+                if isinstance(content.result, dict):
+                    import json
+
+                    content_text = json.dumps(content.result)  # type: ignore
+                elif content.result is not None:
+                    content_text = str(content.result)

        agui_msg: dict[str, Any] = {
+            "id": msg.message_id if msg.message_id else generate_event_id(),  # Always include id
            "role": role,
            "content": content_text,
        }

-        if msg.message_id:
-            agui_msg["id"] = msg.message_id
-
        if tool_calls:
            agui_msg["tool_calls"] = tool_calls

+        # If this is a tool result message, add toolCallId (using camelCase for Pydantic)
+        if tool_result_call_id:
+            agui_msg["toolCallId"] = tool_result_call_id
+            # Tool result messages should have role="tool"
+            agui_msg["role"] = "tool"
+
        result.append(agui_msg)

    return result
@@ -16,9 +16,9 @@ from ag_ui.core import (
    TextMessageEndEvent,
    TextMessageStartEvent,
 )
-from agent_framework import AgentProtocol, AgentThread, TextContent
+from agent_framework import AgentProtocol, AgentThread, ChatAgent, TextContent

-from ._utils import generate_event_id
+from ._utils import convert_agui_tools_to_agent_framework, generate_event_id

 if TYPE_CHECKING:
    from ._agent import AgentConfig
@@ -142,14 +142,10 @@ class HumanInTheLoopOrchestrator(Orchestrator):
            True if last message is a tool result
        """
        msg = context.last_message
-        if not msg or not hasattr(msg, "metadata"):
+        if not msg:
            return False

-        metadata = getattr(msg, "metadata", None)
-        if not metadata:
-            return False
-
-        return bool(metadata.get("is_tool_result", False))
+        return bool(msg.additional_properties.get("is_tool_result", False))

    async def run(
        self,
@@ -274,8 +270,10 @@ class DefaultOrchestrator(Orchestrator):
        current_state: dict[str, Any] = initial_state.copy() if initial_state else {}

        # Check if agent uses structured outputs (response_format)
-        chat_options = getattr(context.agent, "chat_options", None)
-        response_format = getattr(chat_options, "response_format", None) if chat_options else None
+        # Use isinstance to narrow type for proper attribute access
+        response_format = None
+        if isinstance(context.agent, ChatAgent):
+            response_format = context.agent.chat_options.response_format
        skip_text_content = response_format is not None

        # Create event bridge
@@ -334,9 +332,8 @@ class DefaultOrchestrator(Orchestrator):
        if context.messages:
            await thread.on_new_messages(context.messages)

-        # Get the last message as the new input
-        new_message = context.last_message
-        if not new_message:
+        # Use the full incoming message batch to preserve tool-call adjacency
+        if not context.messages:
            logger.warning("No messages provided in AG-UI input")
            yield event_bridge.create_run_finished_event()
            return
@@ -362,11 +359,68 @@ Never replace existing data - always append or merge."""
            )
            messages_to_run.append(state_context_msg)

-        messages_to_run.append(new_message)
+        # Preserve order from client to satisfy provider constraints (assistant tool_calls must
+        # immediately precede tool result messages). Using the full batch avoids reordering.
+        messages_to_run.extend(context.messages)
+
+        # Handle client tools for hybrid execution
+        # Client sends tool metadata, server merges with its own tools.
+        # Client tools have func=None (declaration-only), so @use_function_invocation
+        # will return the function call without executing (passes back to client).
+        from agent_framework import BaseChatClient
+
+        client_tools = convert_agui_tools_to_agent_framework(context.input_data.get("tools"))
+
+        # Extract server tools - use type narrowing when possible
+        server_tools: list[Any] = []
+        if isinstance(context.agent, ChatAgent):
+            server_tools = context.agent.chat_options.tools or []
+        else:
+            # AgentProtocol allows duck-typed implementations - fallback to attribute access
+            # This supports test mocks and custom agent implementations
+            try:
+                chat_options_attr = getattr(context.agent, "chat_options", None)
+                if chat_options_attr is not None:
+                    server_tools = getattr(chat_options_attr, "tools", None) or []
+            except AttributeError:
+                pass
+
+        # Register client tools as additional (declaration-only) so they are not executed on server
+        if client_tools:
+            if isinstance(context.agent, ChatAgent):
+                # Type-safe path for ChatAgent
+                chat_client = context.agent.chat_client
+                if (
+                    isinstance(chat_client, BaseChatClient)
+                    and chat_client.function_invocation_configuration is not None
+                ):
+                    chat_client.function_invocation_configuration.additional_tools = client_tools
+                    logger.debug(
+                        f"[TOOLS] Registered {len(client_tools)} client tools as additional_tools (declaration-only)"
+                    )
+            else:
+                # Fallback for AgentProtocol implementations (test mocks, custom agents)
+                try:
+                    chat_client_attr = getattr(context.agent, "chat_client", None)
+                    if chat_client_attr is not None:
+                        fic = getattr(chat_client_attr, "function_invocation_configuration", None)
+                        if fic is not None:
+                            fic.additional_tools = client_tools  # type: ignore[attr-defined]
+                            logger.debug(
+                                f"[TOOLS] Registered {len(client_tools)} client tools as additional_tools (declaration-only)"
+                            )
+                except AttributeError:
+                    pass
+
+        combined_tools: list[Any] = []
+        if server_tools:
+            combined_tools.extend(server_tools)
+        if client_tools:
+            combined_tools.extend(client_tools)

        # Collect all updates to get the final structured output
        all_updates: list[Any] = []
-        async for update in context.agent.run_stream(messages_to_run, thread=thread):
+        async for update in context.agent.run_stream(messages_to_run, thread=thread, tools=combined_tools or None):
            all_updates.append(update)
            events = await event_bridge.from_agent_run_update(update)
            for event in events:
@@ -374,7 +428,7 @@ Never replace existing data - always append or merge."""

        # After agent completes, check if we should stop (waiting for user to confirm changes)
        if event_bridge.should_stop_after_confirm:
-            logger.info("  >>> Stopping run after confirm_changes - waiting for user response")
+            logger.info("Stopping run after confirm_changes - waiting for user response")
            yield event_bridge.create_run_finished_event()
            return

@@ -4,10 +4,13 @@

 import copy
 import uuid
+from collections.abc import Callable, MutableMapping, Sequence
 from dataclasses import asdict, is_dataclass
 from datetime import date, datetime
 from typing import Any

+from agent_framework import AIFunction, ToolProtocol
+

 def generate_event_id() -> str:
    """Generate a unique event ID."""
@@ -55,3 +58,109 @@ def make_json_safe(obj: Any) -> Any:  # noqa: ANN401
    if isinstance(obj, dict):
        return {key: make_json_safe(value) for key, value in obj.items()}  # type: ignore[misc]
    return str(obj)
+
+
+def convert_agui_tools_to_agent_framework(
+    agui_tools: list[dict[str, Any]] | None,
+) -> list[AIFunction[Any, Any]] | None:
+    """Convert AG-UI tool definitions to Agent Framework AIFunction declarations.
+
+    Creates declaration-only AIFunction instances (no executable implementation).
+    These are used to tell the LLM about available tools. The actual execution
+    happens on the client side via @use_function_invocation.
+
+    CRITICAL: These tools MUST have func=None so that declaration_only returns True.
+    This prevents the server from trying to execute client-side tools.
+
+    Args:
+        agui_tools: List of AG-UI tool definitions with name, description, parameters
+
+    Returns:
+        List of AIFunction declarations, or None if no tools provided
+    """
+    if not agui_tools:
+        return None
+
+    result: list[AIFunction[Any, Any]] = []
+    for tool_def in agui_tools:
+        # Create declaration-only AIFunction (func=None means no implementation)
+        # When func=None, the declaration_only property returns True,
+        # which tells @use_function_invocation to return the function call
+        # without executing it (so it can be sent back to the client)
+        func: AIFunction[Any, Any] = AIFunction(
+            name=tool_def.get("name", ""),
+            description=tool_def.get("description", ""),
+            func=None,  # CRITICAL: Makes declaration_only=True
+            input_model=tool_def.get("parameters", {}),
+        )
+        result.append(func)
+
+    return result
+
+
+def convert_tools_to_agui_format(
+    tools: (
+        ToolProtocol
+        | Callable[..., Any]
+        | MutableMapping[str, Any]
+        | Sequence[ToolProtocol | Callable[..., Any] | MutableMapping[str, Any]]
+        | None
+    ),
+) -> list[dict[str, Any]] | None:
+    """Convert tools to AG-UI format.
+
+    This sends only the metadata (name, description, JSON schema) to the server.
+    The actual executable implementation stays on the client side.
+    The @use_function_invocation decorator handles client-side execution when
+    the server requests a function.
+
+    Args:
+        tools: Tools to convert (single tool or sequence of tools)
+
+    Returns:
+        List of tool specifications in AG-UI format, or None if no tools provided
+    """
+    if not tools:
+        return None
+
+    # Normalize to list
+    if not isinstance(tools, list):
+        tool_list: list[ToolProtocol | Callable[..., Any] | MutableMapping[str, Any]] = [tools]  # type: ignore[list-item]
+    else:
+        tool_list = tools  # type: ignore[assignment]
+
+    results: list[dict[str, Any]] = []
+
+    for tool in tool_list:
+        if isinstance(tool, dict):
+            # Already in dict format, pass through
+            results.append(tool)  # type: ignore[arg-type]
+        elif isinstance(tool, AIFunction):
+            # Convert AIFunction to AG-UI tool format
+            results.append(
+                {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "parameters": tool.parameters(),
+                }
+            )
+        elif callable(tool):
+            # Convert callable to AIFunction first, then to AG-UI format
+            from agent_framework import ai_function
+
+            ai_func = ai_function(tool)
+            results.append(
+                {
+                    "name": ai_func.name,
+                    "description": ai_func.description,
+                    "parameters": ai_func.parameters(),
+                }
+            )
+        elif isinstance(tool, ToolProtocol):
+            # Handle other ToolProtocol implementations
+            # For now, we'll skip non-AIFunction tools as they may not have
+            # the parameters() method. This matches .NET behavior which only
+            # converts AIFunctionDeclaration instances.
+            continue
+
+    return results if results else None
@@ -14,7 +14,7 @@ pip install agent-framework-ag-ui
 from fastapi import FastAPI
 from agent_framework import ChatAgent
 from agent_framework.azure import AzureOpenAIChatClient
-from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint
+from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint

 # Create your agent
 agent = ChatAgent(
@@ -104,7 +104,7 @@ State is injected as system messages and updated via predictive state updates:
 ```python
 from agent_framework import ChatAgent
 from agent_framework.azure import AzureOpenAIChatClient
-from agent_framework_ag_ui import AgentFrameworkAgent
+from agent_framework.ag_ui import AgentFrameworkAgent

 # Create your agent
 agent = ChatAgent(
@@ -141,7 +141,7 @@ Predictive state updates automatically stream tool arguments as optimistic state
 ```python
 from agent_framework import ChatAgent
 from agent_framework.azure import AzureOpenAIChatClient
-from agent_framework_ag_ui import AgentFrameworkAgent
+from agent_framework.ag_ui import AgentFrameworkAgent

 # Create your agent
 agent = ChatAgent(
@@ -170,7 +170,7 @@ Provide domain-specific confirmation messages:
 from typing import Any
 from agent_framework import ChatAgent
 from agent_framework.azure import AzureOpenAIChatClient
-from agent_framework_ag_ui import AgentFrameworkAgent, ConfirmationStrategy
+from agent_framework.ag_ui import AgentFrameworkAgent, ConfirmationStrategy

 class CustomConfirmationStrategy(ConfirmationStrategy):
    def on_approval_accepted(self, steps: list[dict[str, Any]]) -> str:
@@ -216,7 +216,7 @@ def sensitive_action(param: str) -> str:
 Add custom execution flows by implementing the Orchestrator pattern:

 ```python
-from agent_framework_ag_ui._orchestrators import Orchestrator, ExecutionContext
+from agent_framework.ag_ui._orchestrators import Orchestrator, ExecutionContext

 class MyCustomOrchestrator(Orchestrator):
    def can_handle(self, context: ExecutionContext) -> bool:
@@ -128,7 +128,7 @@ class TaskStepsAgentWithExecution:
        import uuid

        logger = logging.getLogger(__name__)
-        logger.info(">>> TaskStepsAgentWithExecution.run_agent() called - wrapper is active")
+        logger.info("TaskStepsAgentWithExecution.run_agent() called - wrapper is active")

        # First, run the base agent to generate the plan - buffer text messages
        final_state: dict[str, Any] | None = None
@@ -138,41 +138,41 @@ class TaskStepsAgentWithExecution:

        async for event in self._base_agent.run_agent(input_data):
            event_type_str = str(event.type) if hasattr(event, "type") else type(event).__name__
-            logger.info(f">>> Processing event: {event_type_str}")
+            logger.info(f"Processing event: {event_type_str}")

            match event:
                case StateSnapshotEvent(snapshot=snapshot):
                    final_state = snapshot
-                    logger.info(f">>> Captured STATE_SNAPSHOT event with state: {final_state}")
+                    logger.info(f"Captured STATE_SNAPSHOT event with state: {final_state}")
                    yield event
                case RunFinishedEvent():
                    run_finished_event = event
-                    logger.info(">>> Captured RUN_FINISHED event - will send after step execution and summary")
+                    logger.info("Captured RUN_FINISHED event - will send after step execution and summary")
                case ToolCallStartEvent(tool_call_id=call_id):
                    tool_call_id = call_id
-                    logger.info(f">>> Captured tool_call_id: {tool_call_id}")
+                    logger.info(f"Captured tool_call_id: {tool_call_id}")
                    yield event
                case TextMessageStartEvent() | TextMessageContentEvent() | TextMessageEndEvent():
                    buffered_text_events.append(event)
-                    logger.info(f">>> Buffered {event_type_str} from first LLM call")
+                    logger.info(f"Buffered {event_type_str} from first LLM call")
                case _:
-                    logger.info(f">>> Yielding event immediately: {event_type_str}")
+                    logger.info(f"Yielding event immediately: {event_type_str}")
                    yield event

-        logger.info(f">>> Base agent completed. Final state: {final_state}")
+        logger.info(f"Base agent completed. Final state: {final_state}")

        # Now simulate executing the steps
        if final_state and "steps" in final_state:
            steps = final_state["steps"]
-            logger.info(f">>> Starting step execution simulation for {len(steps)} steps")
+            logger.info(f"Starting step execution simulation for {len(steps)} steps")

            for i in range(len(steps)):
-                logger.info(f">>> Simulating execution of step {i + 1}/{len(steps)}: {steps[i].get('description')}")
+                logger.info(f"Simulating execution of step {i + 1}/{len(steps)}: {steps[i].get('description')}")
                await asyncio.sleep(1.0)  # Simulate work

                # Update step to completed
                steps[i]["status"] = "completed"
-                logger.info(f">>> Step {i + 1} marked as completed")
+                logger.info(f"Step {i + 1} marked as completed")

                # Send delta event with manual JSON patch format
                delta_event = StateDeltaEvent(
@@ -185,7 +185,7 @@ class TaskStepsAgentWithExecution:
                        }
                    ],
                )
-                logger.info(f">>> Yielding StateDeltaEvent for step {i + 1}")
+                logger.info(f"Yielding StateDeltaEvent for step {i + 1}")
                yield delta_event

            # Send final snapshot
@@ -193,11 +193,11 @@ class TaskStepsAgentWithExecution:
                type=EventType.STATE_SNAPSHOT,
                snapshot={"steps": steps},
            )
-            logger.info(">>> Yielding final StateSnapshotEvent with all steps completed")
+            logger.info("Yielding final StateSnapshotEvent with all steps completed")
            yield final_snapshot

            # SECOND LLM call: Stream summary from chat client directly
-            logger.info(">>> Making SECOND LLM call to generate summary after step execution")
+            logger.info("Making SECOND LLM call to generate summary after step execution")

            # Get the underlying chat agent and client
            chat_agent = self._base_agent.agent  # type: ignore
@@ -236,7 +236,7 @@ class TaskStepsAgentWithExecution:
            )

            # Stream the LLM response and manually emit text events
-            logger.info(">>> Calling chat client for summary")
+            logger.info("Calling chat client for summary")

            message_id = str(uuid.uuid4())

@@ -268,7 +268,7 @@ class TaskStepsAgentWithExecution:
                    type=EventType.TEXT_MESSAGE_END,
                    message_id=message_id,
                )
-                logger.info(f">>> Summary complete: {accumulated_text}")
+                logger.info(f"Summary complete: {accumulated_text}")

                # Build complete message for persistence
                summary_message = {
@@ -285,7 +285,7 @@ class TaskStepsAgentWithExecution:
                    messages=final_messages,
                )
            except Exception as e:
-                logger.error(f">>> Error generating summary: {e}")
+                logger.error(f"Error generating summary: {e}")
                # Generate a new message ID for the error
                error_message_id = str(uuid.uuid4())
                # Yield TEXT_MESSAGE_START for error
@@ -306,11 +306,11 @@ class TaskStepsAgentWithExecution:
                    message_id=error_message_id,
                )
        else:
-            logger.warning(f">>> No steps found in final_state to execute. final_state={final_state}")
+            logger.warning(f"No steps found in final_state to execute. final_state={final_state}")

        # Finally send the original RUN_FINISHED event
        if run_finished_event:
-            logger.info(">>> Yielding original RUN_FINISHED event")
+            logger.info("Yielding original RUN_FINISHED event")
            yield run_finished_event


@@ -2,6 +2,135 @@

 The AG-UI (Agent UI) protocol provides a standardized way for client applications to interact with AI agents over HTTP. This tutorial demonstrates how to build both server and client applications using the AG-UI protocol with Python.

+## Quick Start - Client Examples
+
+If you want to quickly try out the AG-UI client, we provide three ready-to-use examples:
+
+### Basic Interactive Client (`client.py`)
+
+A simple command-line chat client that demonstrates:
+- Streaming responses in real-time
+- Automatic thread management for conversation continuity
+- Direct `AGUIChatClient` usage (caller manages message history)
+
+**Run:**
+```bash
+python client.py
+```
+
+**Note:** This example sends only the current message to the server. The server is responsible for maintaining conversation history using the thread_id.
+
+### Advanced Features Client (`client_advanced.py`)
+
+Demonstrates advanced capabilities:
+- Tool/function calling
+- Both streaming and non-streaming responses
+- Multi-turn conversations
+- Error handling patterns
+
+**Run:**
+```bash
+python client_advanced.py
+```
+
+**Note:** This example shows direct `AGUIChatClient` usage. Tool execution and conversation continuity depend on server-side configuration and capabilities.
+
+### ChatAgent Integration (`client_with_agent.py`)
+
+Best practice example using `ChatAgent` wrapper with **AgentThread**
+- **AgentThread** maintains conversation state
+- Client-side conversation history management via `thread.message_store`
+- **Hybrid tool execution**: client-side + server-side tools simultaneously
+- Full conversation history sent on each request
+- Tool calling with conversation context
+
+**To demonstrate hybrid tools:**
+
+1. **Start server with server-side tool** (Terminal 1):
+   ```bash
+   # Server has get_time_zone tool
+   python server.py
+   ```
+
+2. **Run client with client-side tool** (Terminal 2):
+   ```bash
+   # Client has get_weather tool
+   python client_with_agent.py
+   ```
+
+All examples require a running AG-UI server (see Step 1 below for setup).
+
+## Understanding AG-UI Architecture
+
+### Thread Management
+
+The AG-UI protocol supports two approaches to conversation history:
+
+1. **Server-Managed Threads** (client.py, client_advanced.py)
+   - Client sends only the current message + thread_id
+   - Server maintains full conversation history
+   - Requires server to support stateful thread storage
+   - Lighter network payload
+
+2. **Client-Managed History** (client_with_agent.py)
+   - Client maintains full conversation history locally
+   - Full message history sent with each request
+   - Works with any AG-UI server (stateful or stateless)
+
+The `ChatAgent` wrapper (used in client_with_agent.py) collects messages from local storage and sends the full history to `AGUIChatClient`, which then forwards everything to the server.
+
+### Tool/Function Calling
+
+The AG-UI protocol supports **hybrid tool execution** - both client-side AND server-side tools can coexist in the same conversation.
+
+**The Hybrid Pattern** (client_with_agent.py):
+```
+Client defines:           Server defines:
+- get_weather()          - get_current_time()
+- read_sensors()         - get_server_forecast()
+
+User: "What's the weather in SF and what time is it?"
+    ↓
+ChatAgent sends: full history + tool definitions for get_weather, read_sensors
+    ↓
+Server LLM decides: "I need get_weather('SF') and get_current_time()"
+    ↓
+Server executes get_current_time() → "2025-11-11 14:30:00 UTC"
+Server sends function call request → get_weather('SF')
+    ↓
+ChatAgent intercepts get_weather call → executes locally
+    ↓
+Client sends result → "Sunny, 72°F"
+    ↓
+Server combines both results → "It's sunny and 72°F in SF, and the current time is 2:30 PM UTC"
+    ↓
+Client receives final response
+```
+
+**How it works:**
+
+1. **Client-Side Tools** (`client_with_agent.py`):
+   - Tools defined in ChatAgent's `tools` parameter execute locally
+   - Tool metadata (name, description, schema) sent to server for planning
+   - When server requests client tool → client intercepts → executes locally → sends result
+
+2. **Server-Side Tools**:
+   - Defined in server agent's configuration
+   - Server executes directly without client involvement
+   - Results included in server's response
+
+3. **Hybrid Pattern (Both Together)**:
+   - Server LLM sees ALL tool definitions (client + server)
+   - Decides which to use based on task
+   - Server tools execute server-side
+   - Client tools execute client-side
+
+**Direct AGUIChatClient Usage** (client_advanced.py):
+Even without ChatAgent wrapper, client-side tools work:
+- Tools passed in ChatOptions execute locally
+- Server can also have its own tools
+- Hybrid execution works automatically
+
 ## What is AG-UI?

 AG-UI is a protocol that enables:
@@ -35,13 +164,13 @@ The AG-UI server hosts your AI agent and exposes it via HTTP endpoints using Fas
 ### Install Required Packages

 ```bash
-pip install agent-framework-ag-ui agent-framework-core fastapi uvicorn
+pip install agent-framework-ag-ui
 ```

 Or using uv:

 ```bash
-uv pip install agent-framework-ag-ui agent-framework-core fastapi uvicorn
+uv pip install agent-framework-ag-ui
 ```

 ### Server Code
@@ -57,17 +186,20 @@ import os

 from agent_framework import ChatAgent
 from agent_framework.azure import AzureOpenAIChatClient
-from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint
+from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
 from fastapi import FastAPI

 # Read required configuration
 endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
 deployment_name = os.environ.get("AZURE_OPENAI_DEPLOYMENT_NAME")
+api_key = os.environ.get("AZURE_OPENAI_API_KEY")

 if not endpoint:
    raise ValueError("AZURE_OPENAI_ENDPOINT environment variable is required")
 if not deployment_name:
    raise ValueError("AZURE_OPENAI_DEPLOYMENT_NAME environment variable is required")
+if not api_key:
+    raise ValueError("AZURE_OPENAI_API_KEY environment variable is required")

 # Create the AI agent
 agent = ChatAgent(
@@ -76,6 +208,7 @@ agent = ChatAgent(
    chat_client=AzureOpenAIChatClient(
        endpoint=endpoint,
        deployment_name=deployment_name,
+        api_key=api_key,
    ),
 )

@@ -137,12 +270,14 @@ The server will start listening on `http://127.0.0.1:5100`.

 ## Step 2: Creating an AG-UI Client

-The AG-UI client connects to the remote server and displays streaming responses.
+The AG-UI client connects to the remote server and displays streaming responses. The `AGUIChatClient` is a built-in implementation that integrates with the Agent Framework's standard chat interface.

 ### Install Required Packages

+The `AGUIChatClient` is included in the `agent-framework-ag-ui` package (already installed if you installed the server packages).
+
 ```bash
-pip install httpx
+pip install agent-framework-ag-ui
 ```

 ### Client Code
@@ -152,122 +287,61 @@ Create a file named `client.py`:
 ```python
 # Copyright (c) Microsoft. All rights reserved.

-"""AG-UI client example."""
+"""AG-UI client example using AGUIChatClient."""

 import asyncio
-import json
 import os
-from typing import AsyncIterator

-import httpx
-
-
-class AGUIClient:
-    """Simple AG-UI protocol client."""
-
-    def __init__(self, server_url: str):
-        """Initialize the client.
-
-        Args:
-            server_url: The AG-UI server endpoint URL
-        """
-        self.server_url = server_url
-        self.thread_id: str | None = None
-
-    async def send_message(self, message: str) -> AsyncIterator[dict]:
-        """Send a message and stream the response.
-
-        Args:
-            message: The user message to send
-
-        Yields:
-            AG-UI events from the server
-        """
-        # Prepare the request
-        request_data = {
-            "messages": [
-                {"role": "system", "content": "You are a helpful assistant."},
-                {"role": "user", "content": message},
-            ]
-        }
-
-        # Include thread_id if we have one (for conversation continuity)
-        if self.thread_id:
-            request_data["thread_id"] = self.thread_id
-
-        # Stream the response
-        async with httpx.AsyncClient(timeout=60.0) as client:
-            async with client.stream(
-                "POST",
-                self.server_url,
-                json=request_data,
-                headers={"Accept": "text/event-stream"},
-            ) as response:
-                response.raise_for_status()
-
-                async for line in response.aiter_lines():
-                    # Parse Server-Sent Events format
-                    if line.startswith("data: "):
-                        data = line[6:]  # Remove "data: " prefix
-                        try:
-                            event = json.loads(data)
-                            yield event
-
-                            # Capture thread_id from RUN_STARTED event
-                            if event.get("type") == "RUN_STARTED" and not self.thread_id:
-                                self.thread_id = event.get("threadId")
-                        except json.JSONDecodeError:
-                            continue
+from agent_framework import TextContent
+from agent_framework.ag_ui import AGUIChatClient


 async def main():
-    """Main client loop."""
+    """Main client loop demonstrating AGUIChatClient usage."""
    # Get server URL from environment or use default
    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:5100/")
    print(f"Connecting to AG-UI server at: {server_url}\n")

-    client = AGUIClient(server_url)
+    # Create client with context manager for automatic cleanup
+    async with AGUIChatClient(endpoint=server_url) as client:
+        thread_id: str | None = None

-    try:
-        while True:
-            # Get user input
-            message = input("\nUser (:q or quit to exit): ")
-            if not message.strip():
-                print("Request cannot be empty.")
-                continue
+        try:
+            while True:
+                # Get user input
+                message = input("\nUser (:q or quit to exit): ")
+                if not message.strip():
+                    print("Request cannot be empty.")
+                    continue

-            if message.lower() in (":q", "quit"):
-                break
+                if message.lower() in (":q", "quit"):
+                    break

-            # Send message and display streaming response
-            print("\n", end="")
-            async for event in client.send_message(message):
-                event_type = event.get("type", "")
+                # Send message and stream the response
+                print("\nAssistant: ", end="", flush=True)

-                if event_type == "RUN_STARTED":
-                    thread_id = event.get("threadId", "")
-                    run_id = event.get("runId", "")
-                    print(f"\033[93m[Run Started - Thread: {thread_id}, Run: {run_id}]\033[0m")
+                # Use metadata to maintain conversation continuity
+                metadata = {"thread_id": thread_id} if thread_id else None

-                elif event_type == "TEXT_MESSAGE_CONTENT":
-                    # Stream text content in cyan
-                    print(f"\033[96m{event.get('delta', '')}\033[0m", end="", flush=True)
+                async for update in client.get_streaming_response(message, metadata=metadata):
+                    # Extract thread ID from first update
+                    if not thread_id and update.additional_properties:
+                        thread_id = update.additional_properties.get("thread_id")
+                        if thread_id:
+                            print(f"\n[Thread: {thread_id}]")
+                            print("Assistant: ", end="", flush=True)

-                elif event_type == "RUN_FINISHED":
-                    thread_id = event.get("threadId", "")
-                    run_id = event.get("runId", "")
-                    print(f"\n\033[92m[Run Finished - Thread: {thread_id}, Run: {run_id}]\033[0m")
+                    # Stream text content as it arrives
+                    for content in update.contents:
+                        if isinstance(content, TextContent) and content.text:
+                            print(content.text, end="", flush=True)

-                elif event_type == "RUN_ERROR":
-                    error_message = event.get("message", "Unknown error")
-                    print(f"\n\033[91m[Run Error - Message: {error_message}]\033[0m")
+                print()  # New line after response

-            print()
-
-    except KeyboardInterrupt:
-        print("\n\nExiting...")
-    except Exception as e:
-        print(f"\n\033[91mAn error occurred: {e}\033[0m")
+        except KeyboardInterrupt:
+            print("\n\nExiting...")
+        except Exception as e:
+            print(f"\nAn error occurred: {e}")


 if __name__ == "__main__":
@@ -276,17 +350,13 @@ if __name__ == "__main__":

 ### Key Concepts

- **Server-Sent Events (SSE)**: The protocol uses SSE format (`data: {json}\n\n`)
- **Event Types**: Different events provide metadata and content (all event types use UPPERCASE with underscores):
-  - `RUN_STARTED`: Signals the agent has started processing
-  - `TEXT_MESSAGE_START`: Signals the start of a text message from the agent
-  - `TEXT_MESSAGE_CONTENT`: Incremental text streamed from the agent (with `delta` field)
-  - `TEXT_MESSAGE_END`: Signals the end of a text message
-  - `RUN_FINISHED`: Signals successful completion
-  - `RUN_ERROR`: Error information if something goes wrong
- **Field Naming**: Event fields use camelCase (e.g., `threadId`, `runId`, `messageId`) when accessing JSON events
- **Thread Management**: The `threadId` maintains conversation context across requests
- **Client-Side Instructions**: System messages are sent from the client
+- **`AGUIChatClient`**: Built-in client that implements the Agent Framework's `BaseChatClient` interface
+- **Automatic Event Handling**: The client automatically converts AG-UI events to Agent Framework types
+- **Thread Management**: Pass `thread_id` in metadata to maintain conversation context across requests
+- **Streaming Responses**: Use `get_streaming_response()` for real-time streaming or `get_response()` for non-streaming
+- **Context Manager**: Use `async with` for automatic cleanup of HTTP connections
+- **Standard Interface**: Works with all Agent Framework patterns (ChatAgent, tools, etc.)
+- **Hybrid Tool Execution**: Supports both client-side and server-side tools executing together in the same conversation

 ### Configure and Run the Client

@@ -312,327 +382,13 @@ Connecting to AG-UI server at: http://127.0.0.1:5100/

 User (:q or quit to exit): What is the capital of France?

-[Run Started - Thread: abc123, Run: xyz789]
-The capital of France is Paris. It is known for its rich history, culture,
+[Thread: abc123]
+Assistant: 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: abc123, Run: xyz789]

 User (:q or quit to exit): Tell me a fun fact about space
-
-[Run Started - Thread: abc123, 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: abc123, Run: def456]
-
-User (:q or quit to exit): :q
 ```

-### Color-Coded Output
-
-The client displays different content types with distinct colors:
- **Yellow**: Run started notifications
- **Cyan**: Agent text responses (streamed in real-time)
- **Green**: Run completion notifications
- **Red**: Error messages
-
-## Testing with curl (Optional)
-
-Before running the client, you can test the server manually using curl:
-
-```bash
-curl -N http://127.0.0.1:5100/ \
-  -H "Content-Type: application/json" \
-  -H "Accept: text/event-stream" \
-  -d '{
-    "messages": [
-      {"role": "user", "content": "What is the capital of France?"}
-    ]
-  }'
-```
-
-You should see Server-Sent Events streaming back:
-
-```
-data: {"type":"RUN_STARTED","threadId":"...","runId":"..."}
-
-data: {"type":"TEXT_MESSAGE_START","messageId":"...","role":"assistant"}
-
-data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"...","delta":"The"}
-
-data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"...","delta":" capital"}
-
-...
-
-data: {"type":"TEXT_MESSAGE_END","messageId":"..."}
-
-data: {"type":"RUN_FINISHED","threadId":"...","runId":"..."}
-```
-
-## How It Works
-
-### Server-Side Flow
-
-1. Client sends HTTP POST request with messages
-2. FastAPI endpoint receives the request
-3. `AgentFrameworkAgent` wrapper orchestrates the execution
-4. Agent processes the messages using Agent Framework
-5. `AgentFrameworkEventBridge` converts agent updates to AG-UI events
-6. Responses are streamed back as Server-Sent Events (SSE)
-7. Connection closes when the run completes
-
-### Client-Side Flow
-
-1. Client sends HTTP POST request to server endpoint
-2. Server responds with SSE stream
-3. Client parses incoming `data:` lines as JSON events
-4. Each event is displayed based on its type
-5. `threadId` is captured for conversation continuity
-6. Stream completes when `RUN_FINISHED` event arrives
-
-### Protocol Details
-
-The AG-UI protocol uses:
- **HTTP POST** for sending requests
- **Server-Sent Events (SSE)** for streaming responses
- **JSON** for event serialization
- **Thread IDs** for maintaining conversation context
- **Run IDs** for tracking individual executions
- **Event type naming**: UPPERCASE with underscores (e.g., `RUN_STARTED`, `TEXT_MESSAGE_CONTENT`)
- **Field naming**: camelCase (e.g., `threadId`, `runId`, `messageId`)
-
-## Advanced Features
-
-The Python AG-UI implementation supports all 7 AG-UI features:
-
-### 1. Backend Tool Rendering
-
-Add tools to your agent for backend execution:
-
-```python
-from typing import Any
-
-from agent_framework import ChatAgent, ai_function
-from agent_framework.azure import AzureOpenAIChatClient
-
-
-@ai_function
-def get_weather(location: str) -> dict[str, Any]:
-    """Get weather for a location."""
-    return {"temperature": 72, "conditions": "sunny"}
-
-
-agent = ChatAgent(
-    name="weather_agent",
-    instructions="Use tools to help users.",
-    chat_client=AzureOpenAIChatClient(
-        endpoint="https://your-resource.openai.azure.com/",
-        deployment_name="gpt-4o-mini",
-    ),
-    tools=[get_weather],
-)
-```
-
-The client will receive `TOOL_CALL_START`, `TOOL_CALL_ARGS`, `TOOL_CALL_END`, and `TOOL_CALL_RESULT` events.
-
-### 2. Human in the Loop
-
-Request user confirmation before executing tools:
-
-```python
-from fastapi import FastAPI
-from agent_framework import ChatAgent
-from agent_framework.azure import AzureOpenAIChatClient
-from agent_framework_ag_ui import AgentFrameworkAgent, add_agent_framework_fastapi_endpoint
-
-agent = ChatAgent(
-    name="my_agent",
-    instructions="You are a helpful assistant.",
-    chat_client=AzureOpenAIChatClient(
-        endpoint="https://your-resource.openai.azure.com/",
-        deployment_name="gpt-4o-mini",
-    ),
-)
-
-wrapped_agent = AgentFrameworkAgent(
-    agent=agent,
-    require_confirmation=True,  # Enable human-in-the-loop
-)
-
-app = FastAPI()
-add_agent_framework_fastapi_endpoint(app, wrapped_agent, "/")
-```
-
-The client receives tool approval request events and can send approval responses.
-
-### 3. State Management
-
-Share state between client and server:
-
-```python
-wrapped_agent = AgentFrameworkAgent(
-    agent=agent,
-    state_schema={
-        "location": {"type": "string"},
-        "preferences": {"type": "object"},
-    },
-)
-```
-
-Events include `STATE_SNAPSHOT` and `STATE_DELTA` for bidirectional sync.
-
-### 4. Predictive State Updates
-
-Stream tool arguments as optimistic state updates:
-
-```python
-wrapped_agent = AgentFrameworkAgent(
-    agent=agent,
-    predict_state_config={
-        "location": {"tool": "get_weather", "tool_argument": "location"}
-    },
-    require_confirmation=False,  # Auto-update without confirmation
-)
-```
-
-State updates stream in real-time as the LLM generates tool arguments.
-
-## Common Patterns
-
-### Custom Server Configuration
-
-```python
-from fastapi import FastAPI
-from fastapi.middleware.cors import CORSMiddleware
-
-app = FastAPI()
-
-# Add CORS for web clients
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["*"],
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-add_agent_framework_fastapi_endpoint(app, agent, "/agent")
-```
-
-### Multiple Agents
-
-```python
-app = FastAPI()
-
-weather_agent = ChatAgent(name="weather", ...)
-finance_agent = ChatAgent(name="finance", ...)
-
-add_agent_framework_fastapi_endpoint(app, weather_agent, "/weather")
-add_agent_framework_fastapi_endpoint(app, finance_agent, "/finance")
-```
-
-### Custom Client Timeout
-
-```python
-async with httpx.AsyncClient(timeout=300.0) as client:
-    async with client.stream("POST", server_url, ...) as response:
-        async for line in response.aiter_lines():
-            # Process events
-            pass
-```
-
-### Error Handling
-
-```python
-try:
-    async for event in client.send_message(message):
-        if event.get("type") == "RUN_ERROR":
-            error_msg = event.get("message", "Unknown error")
-            print(f"Error: {error_msg}")
-            # Handle error appropriately
-except httpx.HTTPError as e:
-    print(f"HTTP error: {e}")
-except Exception as e:
-    print(f"Unexpected error: {e}")
-```
-
-### Conversation Continuity
-
-The client automatically maintains `threadId` across requests:
-
-```python
-client = AGUIClient(server_url)
-
-# First message
-async for event in client.send_message("Hello"):
-    # Client captures threadId from RUN_STARTED
-    pass
-
-# Second message - uses same threadId
-async for event in client.send_message("Continue our conversation"):
-    # Conversation context is maintained
-    pass
-```
-
-## AG-UI Event Reference
-
-### Core Events
-
-| Event Type | Description | Key Fields |
-|------------|-------------|------------|
-| `RUN_STARTED` | Agent execution started | `threadId`, `runId` |
-| `RUN_FINISHED` | Agent execution completed | `threadId`, `runId` |
-| `RUN_ERROR` | Agent execution error | `message` |
-
-### Text Message Events
-
-| Event Type | Description | Key Fields |
-|------------|-------------|------------|
-| `TEXT_MESSAGE_START` | Start of agent text message | `messageId`, `role` |
-| `TEXT_MESSAGE_CONTENT` | Streaming text content | `messageId`, `delta` |
-| `TEXT_MESSAGE_END` | End of agent text message | `messageId` |
-
-### Tool Events
-
-| Event Type | Description | Key Fields |
-|------------|-------------|------------|
-| `TOOL_CALL_START` | Tool call initiated | `toolCallId`, `toolCallName` |
-| `TOOL_CALL_ARGS` | Tool arguments streaming | `toolCallId`, `delta` |
-| `TOOL_CALL_END` | Tool call complete | `toolCallId` |
-| `TOOL_CALL_RESULT` | Tool execution result | `toolCallId`, `content` |
-
-### State Events
-
-| Event Type | Description | Key Fields |
-|------------|-------------|------------|
-| `STATE_SNAPSHOT` | Complete state | `snapshot` |
-| `STATE_DELTA` | State changes (JSON Patch) | `delta` |
-
-### Other Events
-
-| Event Type | Description | Key Fields |
-|------------|-------------|------------|
-| `MESSAGES_SNAPSHOT` | Conversation history | `messages` |
-| `CUSTOM` | Custom event data | `name`, `value` |
-
-## Next Steps
-
-Now that you understand the basics of AG-UI, you can:
-
- **Add Tools**: Create custom `@ai_function` tools for your domain
- **Web Integration**: Build React/Vue frontends using the AG-UI protocol
- **State Management**: Implement shared state for generative UI applications
- **Human-in-the-Loop**: Add approval workflows for sensitive operations
- **Deployment**: Deploy to Azure Container Apps or Azure App Service
- **Multi-Agent Systems**: Coordinate multiple specialized agents
- **Monitoring**: Add logging and OpenTelemetry for observability
-
-## Additional Resources
-
- [AG-UI Examples](../agent_framework_ag_ui_examples/README.md): Complete working examples for all 7 features
- [Agent Framework Documentation](../../core/README.md): Learn more about creating agents
- [AG-UI Protocol Spec](https://docs.ag-ui.com/): Official protocol documentation
-
 ## Troubleshooting

 ### Connection Refused
@@ -1,121 +1,71 @@
 # Copyright (c) Microsoft. All rights reserved.

-"""AG-UI client example."""
+"""AG-UI client example using AGUIChatClient.
+
+This example demonstrates how to use the AGUIChatClient to connect to
+a remote AG-UI server and interact with it using the Agent Framework's
+standard chat interface.
+"""

 import asyncio
-import json
 import os
-from collections.abc import AsyncIterator

-import httpx
-
-
-class AGUIClient:
-    """Simple AG-UI protocol client."""
-
-    def __init__(self, server_url: str):
-        """Initialize the client.
-
-        Args:
-            server_url: The AG-UI server endpoint URL
-        """
-        self.server_url = server_url
-        self.thread_id: str | None = None
-
-    async def send_message(self, message: str) -> AsyncIterator[dict]:
-        """Send a message and stream the response.
-
-        Args:
-            message: The user message to send
-
-        Yields:
-            AG-UI events from the server
-        """
-        # Prepare the request
-        request_data: dict[str, object] = {
-            "messages": [
-                {"role": "system", "content": "You are a helpful assistant."},
-                {"role": "user", "content": message},
-            ]
-        }
-
-        # Include thread_id if we have one (for conversation continuity)
-        if self.thread_id:
-            request_data["thread_id"] = self.thread_id
-
-        # Stream the response
-        async with httpx.AsyncClient(timeout=60.0) as client:
-            async with client.stream(
-                "POST",
-                self.server_url,
-                json=request_data,
-                headers={"Accept": "text/event-stream"},
-            ) as response:
-                response.raise_for_status()
-
-                async for line in response.aiter_lines():
-                    # Parse Server-Sent Events format
-                    if line.startswith("data: "):
-                        data = line[6:]  # Remove "data: " prefix
-                        try:
-                            event = json.loads(data)
-                            yield event
-
-                            # Capture thread_id from RUN_STARTED event
-                            if event.get("type") == "RUN_STARTED" and not self.thread_id:
-                                self.thread_id = event.get("threadId")
-                        except json.JSONDecodeError:
-                            continue
+from agent_framework_ag_ui import AGUIChatClient


 async def main():
-    """Main client loop."""
+    """Main client loop demonstrating AGUIChatClient usage."""
    # Get server URL from environment or use default
    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:5100/")
    print(f"Connecting to AG-UI server at: {server_url}\n")
+    print("Using AGUIChatClient with automatic thread management and Agent Framework integration.\n")

-    client = AGUIClient(server_url)
+    # Create client with context manager for automatic cleanup
+    async with AGUIChatClient(endpoint=server_url) as client:
+        thread_id: str | None = None

-    try:
-        while True:
-            # Get user input
-            message = input("\nUser (:q or quit to exit): ")
-            if not message.strip():
-                print("Request cannot be empty.")
-                continue
+        try:
+            while True:
+                # Get user input
+                message = input("\nUser (:q or quit to exit): ")
+                if not message.strip():
+                    print("Request cannot be empty.")
+                    continue

-            if message.lower() in (":q", "quit"):
-                break
+                if message.lower() in (":q", "quit"):
+                    break

-            # Send message and display streaming response
-            print("\n", end="")
-            async for event in client.send_message(message):
-                event_type = event.get("type", "")
+                # Send message and stream the response
+                print("\nAssistant: ", end="", flush=True)

-                if event_type == "RUN_STARTED":
-                    thread_id = event.get("threadId", "")
-                    run_id = event.get("runId", "")
-                    print(f"\033[93m[Run Started - Thread: {thread_id}, Run: {run_id}]\033[0m")
+                # Use metadata to maintain conversation continuity
+                metadata = {"thread_id": thread_id} if thread_id else None

-                elif event_type == "TEXT_MESSAGE_CONTENT":
-                    # Stream text content in cyan
-                    print(f"\033[96m{event.get('delta', '')}\033[0m", end="", flush=True)
+                async for update in client.get_streaming_response(message, metadata=metadata):
+                    # Extract and display thread ID from first update
+                    if not thread_id and update.additional_properties:
+                        thread_id = update.additional_properties.get("thread_id")
+                        if thread_id:
+                            print(f"\n\033[93m[Thread: {thread_id}]\033[0m", end="", flush=True)
+                            print("\nAssistant: ", end="", flush=True)

-                elif event_type == "RUN_FINISHED":
-                    thread_id = event.get("threadId", "")
-                    run_id = event.get("runId", "")
-                    print(f"\n\033[92m[Run Finished - Thread: {thread_id}, Run: {run_id}]\033[0m")
+                    # Display text content as it streams
+                    from agent_framework import TextContent

-                elif event_type == "RUN_ERROR":
-                    error_message = event.get("message", "Unknown error")
-                    print(f"\n\033[91m[Run Error - Message: {error_message}]\033[0m")
+                    for content in update.contents:
+                        if isinstance(content, TextContent) and content.text:
+                            print(f"\033[96m{content.text}\033[0m", end="", flush=True)

-            print()
+                    # Display finish reason if present
+                    if update.finish_reason:
+                        print(f"\n\033[92m[Finished: {update.finish_reason}]\033[0m", end="", flush=True)

-    except KeyboardInterrupt:
-        print("\n\nExiting...")
-    except Exception as e:
-        print(f"\n\033[91mAn error occurred: {e}\033[0m")
+                print()  # New line after response
+
+        except KeyboardInterrupt:
+            print("\n\nExiting...")
+        except Exception as e:
+            print(f"\n\033[91mAn error occurred: {e}\033[0m")


 if __name__ == "__main__":
@@ -0,0 +1,235 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Advanced AG-UI client example with tools and features.
+
+This example demonstrates advanced AGUIChatClient features including:
+- Tool/function calling
+- Non-streaming responses
+- Multiple conversation turns
+- Error handling
+"""
+
+import asyncio
+import os
+
+from agent_framework import ai_function
+
+from agent_framework_ag_ui import AGUIChatClient
+
+
+@ai_function
+def get_weather(location: str) -> str:
+    """Get the current weather for a location.
+
+    Args:
+        location: The city or location name
+    """
+    # Simulate weather lookup
+    weather_data = {
+        "seattle": "Rainy, 55°F",
+        "san francisco": "Foggy, 62°F",
+        "new york": "Sunny, 68°F",
+        "london": "Cloudy, 52°F",
+    }
+    return weather_data.get(location.lower(), f"Weather data not available for {location}")
+
+
+@ai_function
+def calculate(a: float, b: float, operation: str) -> str:
+    """Perform basic arithmetic operations.
+
+    Args:
+        a: First number
+        b: Second number
+        operation: Operation to perform (add, subtract, multiply, divide)
+    """
+    try:
+        if operation == "add":
+            result = a + b
+        elif operation == "subtract":
+            result = a - b
+        elif operation == "multiply":
+            result = a * b
+        elif operation == "divide":
+            result = a / b
+        else:
+            return f"Unsupported operation: {operation}"
+        return f"The result is: {result}"
+    except Exception as e:
+        return f"Error calculating: {e}"
+
+
+async def streaming_example(client: AGUIChatClient, thread_id: str | None = None):
+    """Demonstrate streaming responses."""
+    print("\n" + "=" * 60)
+    print("STREAMING EXAMPLE")
+    print("=" * 60)
+
+    metadata = {"thread_id": thread_id} if thread_id else None
+
+    print("\nUser: Tell me a short joke\n")
+    print("Assistant: ", end="", flush=True)
+
+    async for update in client.get_streaming_response("Tell me a short joke", metadata=metadata):
+        if not thread_id and update.additional_properties:
+            thread_id = update.additional_properties.get("thread_id")
+
+        from agent_framework import TextContent
+
+        for content in update.contents:
+            if isinstance(content, TextContent) and content.text:
+                print(content.text, end="", flush=True)
+
+    print("\n")
+    return thread_id
+
+
+async def non_streaming_example(client: AGUIChatClient, thread_id: str | None = None):
+    """Demonstrate non-streaming responses."""
+    print("\n" + "=" * 60)
+    print("NON-STREAMING EXAMPLE")
+    print("=" * 60)
+
+    metadata = {"thread_id": thread_id} if thread_id else None
+
+    print("\nUser: What is 2 + 2?\n")
+
+    response = await client.get_response("What is 2 + 2?", metadata=metadata)
+
+    print(f"Assistant: {response.text}")
+
+    if response.additional_properties:
+        thread_id = response.additional_properties.get("thread_id")
+        print(f"\n[Thread: {thread_id}]")
+
+    return thread_id
+
+
+async def tool_example(client: AGUIChatClient, thread_id: str | None = None):
+    """Demonstrate sending tool definitions to the server.
+
+    IMPORTANT: When using AGUIChatClient directly (without ChatAgent wrapper):
+    - Tools are sent as DEFINITIONS only
+    - No automatic client-side execution (no function invocation middleware)
+    - Server must have matching tool implementations to execute them
+
+    For CLIENT-SIDE tool execution (like .NET AGUIClient sample):
+    - Use ChatAgent wrapper with tools
+    - See client_with_agent.py for the hybrid pattern
+    - ChatAgent middleware intercepts and executes client tools locally
+    - Server can have its own tools that execute server-side
+    - Both client and server tools work together in same conversation
+
+    This example sends tool definitions and assumes server-side execution.
+    """
+    print("\n" + "=" * 60)
+    print("TOOL DEFINITION EXAMPLE")
+    print("=" * 60)
+
+    metadata = {"thread_id": thread_id} if thread_id else None
+
+    print("\nUser: What's the weather in Seattle?\n")
+    print("Sending tool definitions to server...")
+    print("(Server must be configured with matching tools to execute them)\n")
+
+    response = await client.get_response(
+        "What's the weather in Seattle?", tools=[get_weather, calculate], metadata=metadata
+    )
+
+    print(f"Assistant: {response.text}")
+
+    # Show tool calls if any
+    from agent_framework import FunctionCallContent
+
+    tool_called = False
+    for message in response.messages:
+        for content in message.contents:
+            if isinstance(content, FunctionCallContent):
+                print(f"\n[Tool Called: {content.name}]")
+                tool_called = True
+
+    if not tool_called:
+        print("\n[Note: No tools were called - server may not be configured for tool execution]")
+
+    if response.additional_properties:
+        thread_id = response.additional_properties.get("thread_id")
+
+    return thread_id
+
+
+async def conversation_example(client: AGUIChatClient):
+    """Demonstrate multi-turn conversation.
+
+    Note: Conversation continuity depends on the server maintaining thread state.
+    Some servers may require explicit message history to be sent with each request.
+    """
+    print("\n" + "=" * 60)
+    print("MULTI-TURN CONVERSATION EXAMPLE")
+    print("=" * 60)
+    print("\nNote: This example uses thread_id for context. Server must support thread-based state.\n")
+
+    # First turn
+    print("User: My name is Alice\n")
+    response1 = await client.get_response("My name is Alice")
+    print(f"Assistant: {response1.text}")
+    thread_id = response1.additional_properties.get("thread_id")
+    print(f"\n[Thread: {thread_id}]")
+
+    # Second turn - using same thread
+    print("\nUser: What's my name?\n")
+    response2 = await client.get_response("What's my name?", metadata={"thread_id": thread_id})
+    print(f"Assistant: {response2.text}")
+
+    # Check if context was maintained
+    if "alice" not in response2.text.lower():
+        print("\n[Note: Server may not maintain thread context - consider using ChatAgent for history management]")
+
+    # Third turn
+    print("\nUser: Can you also tell me what 10 * 5 is?\n")
+    response3 = await client.get_response(
+        "Can you also tell me what 10 * 5 is?", metadata={"thread_id": thread_id}, tools=[calculate]
+    )
+    print(f"Assistant: {response3.text}")
+
+
+async def main():
+    """Run all examples."""
+    # Get server URL from environment or use default
+    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:5100/")
+
+    print("=" * 60)
+    print("AG-UI Chat Client Advanced Examples")
+    print("=" * 60)
+    print(f"\nServer: {server_url}")
+    print("\nThese examples demonstrate various AGUIChatClient features:")
+    print("  1. Streaming responses")
+    print("  2. Non-streaming responses")
+    print("  3. Tool/function calling")
+    print("  4. Multi-turn conversations")
+
+    try:
+        async with AGUIChatClient(endpoint=server_url) as client:
+            # Run examples in sequence
+            thread_id = await streaming_example(client)
+            thread_id = await non_streaming_example(client, thread_id)
+            await tool_example(client, thread_id)
+
+            # Separate conversation with new thread
+            await conversation_example(client)
+
+            print("\n" + "=" * 60)
+            print("All examples completed successfully!")
+            print("=" * 60)
+
+    except ConnectionError as e:
+        print(f"\n\033[91mConnection Error: {e}\033[0m")
+        print("\nMake sure an AG-UI server is running at the specified endpoint.")
+    except Exception as e:
+        print(f"\n\033[91mError: {e}\033[0m")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,186 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Example showing ChatAgent with AGUIChatClient for hybrid tool execution.
+
+This demonstrates the HYBRID pattern matching .NET AGUIClient implementation:
+
+1. AgentThread Pattern (like .NET):
+   - Create thread with agent.get_new_thread()
+   - Pass thread to agent.run_stream() on each turn
+   - Thread automatically maintains conversation history via message_store
+
+2. Hybrid Tool Execution:
+   - AGUIChatClient has @use_function_invocation decorator
+   - Client-side tools (get_weather) can execute locally when server requests them
+   - Server may also have its own tools that execute server-side
+   - Both work together: server LLM decides which tool to call, decorator handles client execution
+
+This matches .NET pattern: thread maintains state, tools execute on appropriate side.
+"""
+
+import asyncio
+import logging
+import os
+
+from agent_framework import ChatAgent, FunctionCallContent, FunctionResultContent, TextContent, ai_function
+
+from agent_framework_ag_ui import AGUIChatClient
+
+# Enable debug logging
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+@ai_function(description="Get the current weather for a location.")
+def get_weather(location: str) -> str:
+    """Get the current weather for a location.
+
+    Args:
+        location: The city or location name
+    """
+    print(f"[CLIENT] get_weather tool called with location: {location}")
+    weather_data = {
+        "seattle": "Rainy, 55°F",
+        "san francisco": "Foggy, 62°F",
+        "new york": "Sunny, 68°F",
+        "london": "Cloudy, 52°F",
+    }
+    result = weather_data.get(location.lower(), f"Weather data not available for {location}")
+    print(f"[CLIENT] get_weather returning: {result}")
+    return result
+
+
+async def main():
+    """Demonstrate ChatAgent + AGUIChatClient hybrid tool execution.
+
+    This matches the .NET pattern from Program.cs where:
+    - AIAgent agent = chatClient.CreateAIAgent(tools: [...])
+    - AgentThread thread = agent.GetNewThread()
+    - RunStreamingAsync(messages, thread)
+
+    Python equivalent:
+    - agent = ChatAgent(chat_client=AGUIChatClient(...), tools=[...])
+    - thread = agent.get_new_thread()  # Creates thread with message_store
+    - agent.run_stream(message, thread=thread)  # Thread accumulates history
+    """
+    server_url = os.environ.get("AGUI_SERVER_URL", "http://127.0.0.1:5100/")
+
+    print("=" * 70)
+    print("ChatAgent + AGUIChatClient: Hybrid Tool Execution")
+    print("=" * 70)
+    print(f"\nServer: {server_url}")
+    print("\nThis example demonstrates:")
+    print("  1. AgentThread maintains conversation state (like .NET)")
+    print("  2. Client-side tools execute locally via @use_function_invocation")
+    print("  3. Server may have additional tools that execute server-side")
+    print("  4. HYBRID: Client and server tools work together simultaneously\n")
+
+    try:
+        # Create remote client in async context manager
+        async with AGUIChatClient(endpoint=server_url) as remote_client:
+            # Wrap in ChatAgent for conversation history management
+            agent = ChatAgent(
+                name="remote_assistant",
+                instructions="You are a helpful assistant. Remember user information across the conversation.",
+                chat_client=remote_client,
+                tools=[get_weather],
+            )
+
+            # Create a thread to maintain conversation state (like .NET AgentThread)
+            thread = agent.get_new_thread()
+
+            print("=" * 70)
+            print("CONVERSATION WITH HISTORY")
+            print("=" * 70)
+
+            # Turn 1: Introduce
+            print("\nUser: My name is Alice and I live in Seattle\n")
+            async for chunk in agent.run_stream("My name is Alice and I live in Seattle", thread=thread):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+            print("\n")
+
+            # Turn 2: Ask about name (tests history)
+            print("User: What's my name?\n")
+            async for chunk in agent.run_stream("What's my name?", thread=thread):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+            print("\n")
+
+            # Turn 3: Ask about location (tests history)
+            print("User: Where do I live?\n")
+            async for chunk in agent.run_stream("Where do I live?", thread=thread):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+            print("\n")
+
+            # Turn 4: Test client-side tool (get_weather is client-side)
+            print("User: What's the weather forecast for today in Seattle?\n")
+            async for chunk in agent.run_stream("What's the weather forecast for today in Seattle?", thread=thread):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+            print("\n")
+
+            # Turn 5: Test server-side tool (get_time_zone is server-side only)
+            print("User: What time zone is Seattle in?\n")
+            async for chunk in agent.run_stream("What time zone is Seattle in?", thread=thread):
+                if chunk.text:
+                    print(chunk.text, end="", flush=True)
+            print("\n")
+
+            # Show thread state
+            if thread.message_store:
+
+                def _preview_for_message(m) -> str:
+                    # Prefer plain text when present
+                    if getattr(m, "text", ""):
+                        t = m.text
+                        return (t[:60] + "...") if len(t) > 60 else t
+                    # Build from contents when no direct text
+                    parts: list[str] = []
+                    for c in getattr(m, "contents", []) or []:
+                        if isinstance(c, FunctionCallContent):
+                            args = c.arguments
+                            if isinstance(args, dict):
+                                try:
+                                    import json as _json
+
+                                    args_str = _json.dumps(args)
+                                except Exception:
+                                    args_str = str(args)
+                            else:
+                                args_str = str(args or "{}")
+                            parts.append(f"tool_call {c.name} {args_str}")
+                        elif isinstance(c, FunctionResultContent):
+                            parts.append(f"tool_result[{c.call_id}]: {str(c.result)[:40]}")
+                        elif isinstance(c, TextContent):
+                            if c.text:
+                                parts.append(c.text)
+                        else:
+                            typename = getattr(c, "type", c.__class__.__name__)
+                            parts.append(f"<{typename}>")
+                    preview = " | ".join(parts) if parts else ""
+                    return (preview[:60] + "...") if len(preview) > 60 else preview
+
+                messages = await thread.message_store.list_messages()
+                print(f"\n[THREAD STATE] {len(messages)} messages in thread's message_store")
+                for i, msg in enumerate(messages[-6:], 1):  # Show last 6
+                    role = msg.role.value if hasattr(msg.role, "value") else str(msg.role)
+                    text_preview = _preview_for_message(msg)
+                    print(f"  {i}. [{role}]: {text_preview}")
+
+    except ConnectionError as e:
+        print(f"\n\033[91mConnection Error: {e}\033[0m")
+        print("\nMake sure an AG-UI server is running at the specified endpoint.")
+    except Exception as e:
+        print(f"\n\033[91mError: {e}\033[0m")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -1,18 +1,26 @@
 # Copyright (c) Microsoft. All rights reserved.

-"""AG-UI server example."""
+"""AG-UI server example with server-side tools."""

+import logging
 import os

-from agent_framework import ChatAgent
+from agent_framework import ChatAgent, ai_function
+from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
 from agent_framework.azure import AzureOpenAIChatClient
 from dotenv import load_dotenv
 from fastapi import FastAPI

-from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint
-
 load_dotenv()

+# Enable debug logging
+logging.basicConfig(
+    level=logging.DEBUG,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
 # Read required configuration
 endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
 deployment_name = os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME")
@@ -22,14 +30,43 @@ if not endpoint:
 if not deployment_name:
    raise ValueError("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME environment variable is required")

-# Create the AI agent
+
+# Server-side tool (executes on server)
+@ai_function(description="Get the time zone for a location.")
+def get_time_zone(location: str) -> str:
+    """Get the time zone for a location.
+
+    Args:
+        location: The city or location name
+    """
+    print(f"[SERVER] get_time_zone tool called with location: {location}")
+    timezone_data = {
+        "seattle": "Pacific Time (UTC-8)",
+        "san francisco": "Pacific Time (UTC-8)",
+        "new york": "Eastern Time (UTC-5)",
+        "london": "Greenwich Mean Time (UTC+0)",
+    }
+    result = timezone_data.get(location.lower(), f"Time zone data not available for {location}")
+    print(f"[SERVER] get_time_zone returning: {result}")
+    return result
+
+
+# Create the AI agent with ONLY server-side tools
+# IMPORTANT: Do NOT include tools that the client provides!
+# In this example:
+# - get_time_zone: SERVER-ONLY tool (only server has this)
+# - get_weather: CLIENT-ONLY tool (client provides this, server should NOT include it)
+# The client will send get_weather tool metadata so the LLM knows about it,
+# and @use_function_invocation on AGUIChatClient will execute it client-side.
+# This matches the .NET AG-UI hybrid execution pattern.
 agent = ChatAgent(
    name="AGUIAssistant",
-    instructions="You are a helpful assistant.",
+    instructions="You are a helpful assistant. Use get_weather for weather and get_time_zone for time zones.",
    chat_client=AzureOpenAIChatClient(
        endpoint=endpoint,
        deployment_name=deployment_name,
    ),
+    tools=[get_time_zone],  # ONLY server-side tools
 )

 # Create FastAPI app
@@ -41,4 +78,4 @@ add_agent_framework_fastapi_endpoint(app, agent, "/")
 if __name__ == "__main__":
    import uvicorn

-    uvicorn.run(app, host="127.0.0.1", port=5100)
+    uvicorn.run(app, host="127.0.0.1", port=5100, log_level="debug", access_log=True)
@@ -1,6 +1,6 @@
 [project]
 name = "agent-framework-ag-ui"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 description = "AG-UI protocol integration for Agent Framework"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -0,0 +1,317 @@
+"""Tests for AGUIChatClient."""
+
+import json
+
+from agent_framework import ChatMessage, ChatOptions, FunctionCallContent, Role, ai_function
+
+from agent_framework_ag_ui._client import AGUIChatClient, ServerFunctionCallContent
+
+
+class TestAGUIChatClient:
+    """Test suite for AGUIChatClient."""
+
+    async def test_client_initialization(self) -> None:
+        """Test client initialization."""
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+
+        assert client._http_service is not None
+        assert client._http_service.endpoint.startswith("http://localhost:8888")
+
+    async def test_client_context_manager(self) -> None:
+        """Test client as async context manager."""
+        async with AGUIChatClient(endpoint="http://localhost:8888/") as client:
+            assert client is not None
+
+    async def test_extract_state_from_messages_no_state(self) -> None:
+        """Test state extraction when no state is present."""
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+        messages = [
+            ChatMessage(role="user", text="Hello"),
+            ChatMessage(role="assistant", text="Hi there"),
+        ]
+
+        result_messages, state = client._extract_state_from_messages(messages)
+
+        assert result_messages == messages
+        assert state is None
+
+    async def test_extract_state_from_messages_with_state(self) -> None:
+        """Test state extraction from last message."""
+        import base64
+
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+
+        state_data = {"key": "value", "count": 42}
+        state_json = json.dumps(state_data)
+        state_b64 = base64.b64encode(state_json.encode("utf-8")).decode("utf-8")
+
+        from agent_framework import DataContent
+
+        messages = [
+            ChatMessage(role="user", text="Hello"),
+            ChatMessage(
+                role="user",
+                contents=[DataContent(uri=f"data:application/json;base64,{state_b64}")],
+            ),
+        ]
+
+        result_messages, state = client._extract_state_from_messages(messages)
+
+        assert len(result_messages) == 1
+        assert result_messages[0].text == "Hello"
+        assert state == state_data
+
+    async def test_extract_state_invalid_json(self) -> None:
+        """Test state extraction with invalid JSON."""
+        import base64
+
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+
+        invalid_json = "not valid json"
+        state_b64 = base64.b64encode(invalid_json.encode("utf-8")).decode("utf-8")
+
+        from agent_framework import DataContent
+
+        messages = [
+            ChatMessage(
+                role="user",
+                contents=[DataContent(uri=f"data:application/json;base64,{state_b64}")],
+            ),
+        ]
+
+        result_messages, state = client._extract_state_from_messages(messages)
+
+        assert result_messages == messages
+        assert state is None
+
+    async def test_convert_messages_to_agui_format(self) -> None:
+        """Test message conversion to AG-UI format."""
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+        messages = [
+            ChatMessage(role=Role.USER, text="What is the weather?"),
+            ChatMessage(role=Role.ASSISTANT, text="Let me check.", message_id="msg_123"),
+        ]
+
+        agui_messages = client._convert_messages_to_agui_format(messages)
+
+        assert len(agui_messages) == 2
+        assert agui_messages[0]["role"] == "user"
+        assert agui_messages[0]["content"] == "What is the weather?"
+        assert agui_messages[1]["role"] == "assistant"
+        assert agui_messages[1]["content"] == "Let me check."
+        assert agui_messages[1]["id"] == "msg_123"
+
+    async def test_get_thread_id_from_metadata(self) -> None:
+        """Test thread ID extraction from metadata."""
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+        chat_options = ChatOptions(metadata={"thread_id": "existing_thread_123"})
+
+        thread_id = client._get_thread_id(chat_options)
+
+        assert thread_id == "existing_thread_123"
+
+    async def test_get_thread_id_generation(self) -> None:
+        """Test automatic thread ID generation."""
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+        chat_options = ChatOptions()
+
+        thread_id = client._get_thread_id(chat_options)
+
+        assert thread_id.startswith("thread_")
+        assert len(thread_id) > 7
+
+    async def test_get_streaming_response(self, monkeypatch) -> None:
+        """Test streaming response method."""
+        mock_events = [
+            {"type": "RUN_STARTED", "threadId": "thread_1", "runId": "run_1"},
+            {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": "Hello"},
+            {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": " world"},
+            {"type": "RUN_FINISHED", "threadId": "thread_1", "runId": "run_1"},
+        ]
+
+        async def mock_post_run(*args, **kwargs):
+            for event in mock_events:
+                yield event
+
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+        monkeypatch.setattr(client._http_service, "post_run", mock_post_run)
+
+        messages = [ChatMessage(role="user", text="Test message")]
+        chat_options = ChatOptions()
+
+        updates = []
+        async for update in client._inner_get_streaming_response(messages=messages, chat_options=chat_options):
+            updates.append(update)
+
+        assert len(updates) == 4
+        assert updates[0].additional_properties["thread_id"] == "thread_1"
+        assert updates[1].contents[0].text == "Hello"
+        assert updates[2].contents[0].text == " world"
+
+    async def test_get_response_non_streaming(self, monkeypatch) -> None:
+        """Test non-streaming response method."""
+        mock_events = [
+            {"type": "RUN_STARTED", "threadId": "thread_1", "runId": "run_1"},
+            {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": "Complete response"},
+            {"type": "RUN_FINISHED", "threadId": "thread_1", "runId": "run_1"},
+        ]
+
+        async def mock_post_run(*args, **kwargs):
+            for event in mock_events:
+                yield event
+
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+        monkeypatch.setattr(client._http_service, "post_run", mock_post_run)
+
+        messages = [ChatMessage(role="user", text="Test message")]
+        chat_options = ChatOptions()
+
+        response = await client._inner_get_response(messages=messages, chat_options=chat_options)
+
+        assert response is not None
+        assert len(response.messages) > 0
+        assert "Complete response" in response.text
+
+    async def test_tool_handling(self, monkeypatch) -> None:
+        """Test that client tool metadata is sent to server.
+
+        Client tool metadata (name, description, schema) is sent to server for planning.
+        When server requests a client function, @use_function_invocation decorator
+        intercepts and executes it locally. This matches .NET AG-UI implementation.
+        """
+        from agent_framework import ai_function
+
+        @ai_function
+        def test_tool(param: str) -> str:
+            """Test tool."""
+            return "result"
+
+        mock_events = [
+            {"type": "RUN_STARTED", "threadId": "thread_1", "runId": "run_1"},
+            {"type": "RUN_FINISHED", "threadId": "thread_1", "runId": "run_1"},
+        ]
+
+        async def mock_post_run(*args, **kwargs):
+            # Client tool metadata should be sent to server
+            tools = kwargs.get("tools")
+            assert tools is not None
+            assert len(tools) == 1
+            assert tools[0]["name"] == "test_tool"
+            assert tools[0]["description"] == "Test tool."
+            assert "parameters" in tools[0]
+            for event in mock_events:
+                yield event
+
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+        monkeypatch.setattr(client._http_service, "post_run", mock_post_run)
+
+        messages = [ChatMessage(role="user", text="Test with tools")]
+        chat_options = ChatOptions(tools=[test_tool])
+
+        response = await client._inner_get_response(messages=messages, chat_options=chat_options)
+
+        assert response is not None
+
+    async def test_server_tool_calls_unwrapped_after_invocation(self, monkeypatch) -> None:
+        """Ensure server-side tool calls are exposed as FunctionCallContent after processing."""
+
+        mock_events = [
+            {"type": "RUN_STARTED", "threadId": "thread_1", "runId": "run_1"},
+            {"type": "TOOL_CALL_START", "toolCallId": "call_1", "toolName": "get_time_zone"},
+            {"type": "TOOL_CALL_ARGS", "toolCallId": "call_1", "delta": '{"location": "Seattle"}'},
+            {"type": "RUN_FINISHED", "threadId": "thread_1", "runId": "run_1"},
+        ]
+
+        async def mock_post_run(*args, **kwargs):
+            for event in mock_events:
+                yield event
+
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+        monkeypatch.setattr(client._http_service, "post_run", mock_post_run)
+
+        messages = [ChatMessage(role="user", text="Test server tool execution")]
+        chat_options = ChatOptions()
+
+        updates = []
+        async for update in client.get_streaming_response(messages, chat_options=chat_options):
+            updates.append(update)
+
+        function_calls = [
+            content for update in updates for content in update.contents if isinstance(content, FunctionCallContent)
+        ]
+        assert function_calls
+        assert function_calls[0].name == "get_time_zone"
+        assert not any(
+            isinstance(content, ServerFunctionCallContent) for update in updates for content in update.contents
+        )
+
+    async def test_server_tool_calls_not_executed_locally(self, monkeypatch) -> None:
+        """Server tools should not trigger local function invocation even when client tools exist."""
+
+        @ai_function
+        def client_tool() -> str:
+            """Client tool stub."""
+            return "client"
+
+        mock_events = [
+            {"type": "RUN_STARTED", "threadId": "thread_1", "runId": "run_1"},
+            {"type": "TOOL_CALL_START", "toolCallId": "call_1", "toolName": "get_time_zone"},
+            {"type": "TOOL_CALL_ARGS", "toolCallId": "call_1", "delta": '{"location": "Seattle"}'},
+            {"type": "RUN_FINISHED", "threadId": "thread_1", "runId": "run_1"},
+        ]
+
+        async def mock_post_run(*args, **kwargs):
+            for event in mock_events:
+                yield event
+
+        async def fake_auto_invoke(*args, **kwargs):
+            function_call = kwargs.get("function_call_content") or args[0]
+            raise AssertionError(f"Unexpected local execution of server tool: {getattr(function_call, 'name', '?')}")
+
+        monkeypatch.setattr("agent_framework._tools._auto_invoke_function", fake_auto_invoke)
+
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+        monkeypatch.setattr(client._http_service, "post_run", mock_post_run)
+
+        messages = [ChatMessage(role="user", text="Test server tool execution")]
+        chat_options = ChatOptions(tool_choice="auto", tools=[client_tool])
+
+        async for _ in client.get_streaming_response(messages, chat_options=chat_options):
+            pass
+
+    async def test_state_transmission(self, monkeypatch) -> None:
+        """Test state is properly transmitted to server."""
+        import base64
+
+        state_data = {"user_id": "123", "session": "abc"}
+        state_json = json.dumps(state_data)
+        state_b64 = base64.b64encode(state_json.encode("utf-8")).decode("utf-8")
+
+        from agent_framework import DataContent
+
+        messages = [
+            ChatMessage(role="user", text="Hello"),
+            ChatMessage(
+                role="user",
+                contents=[DataContent(uri=f"data:application/json;base64,{state_b64}")],
+            ),
+        ]
+
+        mock_events = [
+            {"type": "RUN_STARTED", "threadId": "thread_1", "runId": "run_1"},
+            {"type": "RUN_FINISHED", "threadId": "thread_1", "runId": "run_1"},
+        ]
+
+        async def mock_post_run(*args, **kwargs):
+            assert kwargs.get("state") == state_data
+            for event in mock_events:
+                yield event
+
+        client = AGUIChatClient(endpoint="http://localhost:8888/")
+        monkeypatch.setattr(client._http_service, "post_run", mock_post_run)
+
+        chat_options = ChatOptions()
+
+        response = await client._inner_get_response(messages=messages, chat_options=chat_options)
+
+        assert response is not None
@@ -0,0 +1,287 @@
+"""Tests for AG-UI event converter."""
+
+from agent_framework import FinishReason, Role
+
+from agent_framework_ag_ui._event_converters import AGUIEventConverter
+
+
+class TestAGUIEventConverter:
+    """Test suite for AGUIEventConverter."""
+
+    def test_run_started_event(self) -> None:
+        """Test conversion of RUN_STARTED event."""
+        converter = AGUIEventConverter()
+        event = {
+            "type": "RUN_STARTED",
+            "threadId": "thread_123",
+            "runId": "run_456",
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is not None
+        assert update.role == Role.ASSISTANT
+        assert update.additional_properties["thread_id"] == "thread_123"
+        assert update.additional_properties["run_id"] == "run_456"
+        assert converter.thread_id == "thread_123"
+        assert converter.run_id == "run_456"
+
+    def test_text_message_start_event(self) -> None:
+        """Test conversion of TEXT_MESSAGE_START event."""
+        converter = AGUIEventConverter()
+        event = {
+            "type": "TEXT_MESSAGE_START",
+            "messageId": "msg_789",
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is not None
+        assert update.role == Role.ASSISTANT
+        assert update.message_id == "msg_789"
+        assert converter.current_message_id == "msg_789"
+
+    def test_text_message_content_event(self) -> None:
+        """Test conversion of TEXT_MESSAGE_CONTENT event."""
+        converter = AGUIEventConverter()
+        event = {
+            "type": "TEXT_MESSAGE_CONTENT",
+            "messageId": "msg_1",
+            "delta": "Hello",
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is not None
+        assert update.role == Role.ASSISTANT
+        assert update.message_id == "msg_1"
+        assert len(update.contents) == 1
+        assert update.contents[0].text == "Hello"
+
+    def test_text_message_streaming(self) -> None:
+        """Test streaming text across multiple TEXT_MESSAGE_CONTENT events."""
+        converter = AGUIEventConverter()
+        events = [
+            {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": "Hello"},
+            {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": " world"},
+            {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": "!"},
+        ]
+
+        updates = [converter.convert_event(event) for event in events]
+
+        assert all(update is not None for update in updates)
+        assert all(update.message_id == "msg_1" for update in updates)
+        assert updates[0].contents[0].text == "Hello"
+        assert updates[1].contents[0].text == " world"
+        assert updates[2].contents[0].text == "!"
+
+    def test_text_message_end_event(self) -> None:
+        """Test conversion of TEXT_MESSAGE_END event."""
+        converter = AGUIEventConverter()
+        event = {
+            "type": "TEXT_MESSAGE_END",
+            "messageId": "msg_1",
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is None
+
+    def test_tool_call_start_event(self) -> None:
+        """Test conversion of TOOL_CALL_START event."""
+        converter = AGUIEventConverter()
+        event = {
+            "type": "TOOL_CALL_START",
+            "toolCallId": "call_123",
+            "toolName": "get_weather",
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is not None
+        assert update.role == Role.ASSISTANT
+        assert len(update.contents) == 1
+        assert update.contents[0].call_id == "call_123"
+        assert update.contents[0].name == "get_weather"
+        assert update.contents[0].arguments == ""
+        assert converter.current_tool_call_id == "call_123"
+        assert converter.current_tool_name == "get_weather"
+
+    def test_tool_call_start_with_tool_call_name(self) -> None:
+        """Ensure TOOL_CALL_START with toolCallName still sets the tool name."""
+        converter = AGUIEventConverter()
+        event = {
+            "type": "TOOL_CALL_START",
+            "toolCallId": "call_abc",
+            "toolCallName": "get_weather",
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is not None
+        assert update.contents[0].name == "get_weather"
+        assert converter.current_tool_name == "get_weather"
+
+    def test_tool_call_start_with_tool_call_name_snake_case(self) -> None:
+        """Support tool_call_name snake_case field for backwards compatibility."""
+        converter = AGUIEventConverter()
+        event = {
+            "type": "TOOL_CALL_START",
+            "toolCallId": "call_snake",
+            "tool_call_name": "get_weather",
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is not None
+        assert update.contents[0].name == "get_weather"
+        assert converter.current_tool_name == "get_weather"
+
+    def test_tool_call_args_streaming(self) -> None:
+        """Test streaming tool arguments across multiple TOOL_CALL_ARGS events."""
+        converter = AGUIEventConverter()
+        converter.current_tool_call_id = "call_123"
+        converter.current_tool_name = "search"
+
+        events = [
+            {"type": "TOOL_CALL_ARGS", "delta": '{"query": "'},
+            {"type": "TOOL_CALL_ARGS", "delta": 'latest news"}'},
+        ]
+
+        updates = [converter.convert_event(event) for event in events]
+
+        assert all(update is not None for update in updates)
+        assert updates[0].contents[0].arguments == '{"query": "'
+        assert updates[1].contents[0].arguments == 'latest news"}'
+        assert converter.accumulated_tool_args == '{"query": "latest news"}'
+
+    def test_tool_call_end_event(self) -> None:
+        """Test conversion of TOOL_CALL_END event."""
+        converter = AGUIEventConverter()
+        converter.accumulated_tool_args = '{"location": "Seattle"}'
+
+        event = {
+            "type": "TOOL_CALL_END",
+            "toolCallId": "call_123",
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is None
+        assert converter.accumulated_tool_args == ""
+
+    def test_tool_call_result_event(self) -> None:
+        """Test conversion of TOOL_CALL_RESULT event."""
+        converter = AGUIEventConverter()
+        event = {
+            "type": "TOOL_CALL_RESULT",
+            "toolCallId": "call_123",
+            "result": {"temperature": 22, "condition": "sunny"},
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is not None
+        assert update.role == Role.TOOL
+        assert len(update.contents) == 1
+        assert update.contents[0].call_id == "call_123"
+        assert update.contents[0].result == {"temperature": 22, "condition": "sunny"}
+
+    def test_run_finished_event(self) -> None:
+        """Test conversion of RUN_FINISHED event."""
+        converter = AGUIEventConverter()
+        converter.thread_id = "thread_123"
+        converter.run_id = "run_456"
+
+        event = {
+            "type": "RUN_FINISHED",
+            "threadId": "thread_123",
+            "runId": "run_456",
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is not None
+        assert update.role == Role.ASSISTANT
+        assert update.finish_reason == FinishReason.STOP
+        assert update.additional_properties["thread_id"] == "thread_123"
+        assert update.additional_properties["run_id"] == "run_456"
+
+    def test_run_error_event(self) -> None:
+        """Test conversion of RUN_ERROR event."""
+        converter = AGUIEventConverter()
+        converter.thread_id = "thread_123"
+        converter.run_id = "run_456"
+
+        event = {
+            "type": "RUN_ERROR",
+            "message": "Connection timeout",
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is not None
+        assert update.role == Role.ASSISTANT
+        assert update.finish_reason == FinishReason.CONTENT_FILTER
+        assert len(update.contents) == 1
+        assert update.contents[0].message == "Connection timeout"
+        assert update.contents[0].error_code == "RUN_ERROR"
+
+    def test_unknown_event_type(self) -> None:
+        """Test handling of unknown event types."""
+        converter = AGUIEventConverter()
+        event = {
+            "type": "UNKNOWN_EVENT",
+            "data": "some data",
+        }
+
+        update = converter.convert_event(event)
+
+        assert update is None
+
+    def test_full_conversation_flow(self) -> None:
+        """Test complete conversation flow with multiple event types."""
+        converter = AGUIEventConverter()
+
+        events = [
+            {"type": "RUN_STARTED", "threadId": "thread_1", "runId": "run_1"},
+            {"type": "TEXT_MESSAGE_START", "messageId": "msg_1"},
+            {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": "I'll check"},
+            {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": " the weather."},
+            {"type": "TEXT_MESSAGE_END", "messageId": "msg_1"},
+            {"type": "TOOL_CALL_START", "toolCallId": "call_1", "toolName": "get_weather"},
+            {"type": "TOOL_CALL_ARGS", "delta": '{"location": "Seattle"}'},
+            {"type": "TOOL_CALL_END", "toolCallId": "call_1"},
+            {"type": "TOOL_CALL_RESULT", "toolCallId": "call_1", "result": "Sunny, 72°F"},
+            {"type": "TEXT_MESSAGE_START", "messageId": "msg_2"},
+            {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_2", "delta": "It's sunny!"},
+            {"type": "TEXT_MESSAGE_END", "messageId": "msg_2"},
+            {"type": "RUN_FINISHED", "threadId": "thread_1", "runId": "run_1"},
+        ]
+
+        updates = [converter.convert_event(event) for event in events]
+        non_none_updates = [u for u in updates if u is not None]
+
+        assert len(non_none_updates) == 10
+        assert converter.thread_id == "thread_1"
+        assert converter.run_id == "run_1"
+
+    def test_multiple_tool_calls(self) -> None:
+        """Test handling multiple tool calls in sequence."""
+        converter = AGUIEventConverter()
+
+        events = [
+            {"type": "TOOL_CALL_START", "toolCallId": "call_1", "toolName": "search"},
+            {"type": "TOOL_CALL_ARGS", "delta": '{"query": "weather"}'},
+            {"type": "TOOL_CALL_END", "toolCallId": "call_1"},
+            {"type": "TOOL_CALL_START", "toolCallId": "call_2", "toolName": "fetch"},
+            {"type": "TOOL_CALL_ARGS", "delta": '{"url": "http://api.weather.com"}'},
+            {"type": "TOOL_CALL_END", "toolCallId": "call_2"},
+        ]
+
+        updates = [converter.convert_event(event) for event in events]
+        non_none_updates = [u for u in updates if u is not None]
+
+        assert len(non_none_updates) == 4
+        assert non_none_updates[0].contents[0].name == "search"
+        assert non_none_updates[2].contents[0].name == "fetch"
@@ -0,0 +1,238 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for AGUIHttpService."""
+
+import json
+from unittest.mock import AsyncMock, Mock
+
+import httpx
+import pytest
+
+from agent_framework_ag_ui._http_service import AGUIHttpService
+
+
+@pytest.fixture
+def mock_http_client():
+    """Create a mock httpx.AsyncClient."""
+    client = AsyncMock(spec=httpx.AsyncClient)
+    return client
+
+
+@pytest.fixture
+def sample_events():
+    """Sample AG-UI events for testing."""
+    return [
+        {"type": "RUN_STARTED", "threadId": "thread_123", "runId": "run_456"},
+        {"type": "TEXT_MESSAGE_START", "messageId": "msg_1", "role": "assistant"},
+        {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": "Hello"},
+        {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": " world"},
+        {"type": "TEXT_MESSAGE_END", "messageId": "msg_1"},
+        {"type": "RUN_FINISHED", "threadId": "thread_123", "runId": "run_456"},
+    ]
+
+
+def create_sse_response(events: list[dict]) -> str:
+    """Create SSE formatted response from events."""
+    lines = []
+    for event in events:
+        lines.append(f"data: {json.dumps(event)}\n")
+    return "\n".join(lines)
+
+
+async def test_http_service_initialization():
+    """Test AGUIHttpService initialization."""
+    # Test with default client
+    service = AGUIHttpService("http://localhost:8888/")
+    assert service.endpoint == "http://localhost:8888"
+    assert service._owns_client is True
+    assert isinstance(service.http_client, httpx.AsyncClient)
+    await service.close()
+
+    # Test with custom client
+    custom_client = httpx.AsyncClient()
+    service = AGUIHttpService("http://localhost:8888/", http_client=custom_client)
+    assert service._owns_client is False
+    assert service.http_client is custom_client
+    # Shouldn't close the custom client
+    await service.close()
+    await custom_client.aclose()
+
+
+async def test_http_service_strips_trailing_slash():
+    """Test that endpoint trailing slash is stripped."""
+    service = AGUIHttpService("http://localhost:8888/")
+    assert service.endpoint == "http://localhost:8888"
+    await service.close()
+
+
+async def test_post_run_successful_streaming(mock_http_client, sample_events):
+    """Test successful streaming of events."""
+
+    # Create async generator for lines
+    async def mock_aiter_lines():
+        sse_data = create_sse_response(sample_events)
+        for line in sse_data.split("\n"):
+            if line:
+                yield line
+
+    # Create mock response
+    mock_response = AsyncMock()
+    mock_response.status_code = 200
+    # aiter_lines is called as a method, so it should return a new generator each time
+    mock_response.aiter_lines = mock_aiter_lines
+
+    # Setup mock streaming context manager
+    mock_stream_context = AsyncMock()
+    mock_stream_context.__aenter__.return_value = mock_response
+    mock_stream_context.__aexit__.return_value = None
+    mock_http_client.stream.return_value = mock_stream_context
+
+    service = AGUIHttpService("http://localhost:8888/", http_client=mock_http_client)
+
+    events = []
+    async for event in service.post_run(
+        thread_id="thread_123", run_id="run_456", messages=[{"role": "user", "content": "Hello"}]
+    ):
+        events.append(event)
+
+    assert len(events) == len(sample_events)
+    assert events[0]["type"] == "RUN_STARTED"
+    assert events[-1]["type"] == "RUN_FINISHED"
+
+    # Verify request was made correctly
+    mock_http_client.stream.assert_called_once()
+    call_args = mock_http_client.stream.call_args
+    assert call_args.args[0] == "POST"
+    assert call_args.args[1] == "http://localhost:8888"
+    assert call_args.kwargs["headers"] == {"Accept": "text/event-stream"}
+
+
+async def test_post_run_with_state_and_tools(mock_http_client):
+    """Test posting run with state and tools."""
+
+    async def mock_aiter_lines():
+        return
+        yield  # Make it an async generator
+
+    mock_response = AsyncMock()
+    mock_response.status_code = 200
+    mock_response.aiter_lines = mock_aiter_lines
+
+    mock_stream_context = AsyncMock()
+    mock_stream_context.__aenter__.return_value = mock_response
+    mock_stream_context.__aexit__.return_value = None
+    mock_http_client.stream.return_value = mock_stream_context
+
+    service = AGUIHttpService("http://localhost:8888/", http_client=mock_http_client)
+
+    state = {"user_context": {"name": "Alice"}}
+    tools = [{"type": "function", "function": {"name": "test_tool"}}]
+
+    async for _ in service.post_run(thread_id="thread_123", run_id="run_456", messages=[], state=state, tools=tools):
+        pass
+
+    # Verify state and tools were included in request
+    call_args = mock_http_client.stream.call_args
+    request_data = call_args.kwargs["json"]
+    assert request_data["state"] == state
+    assert request_data["tools"] == tools
+
+
+async def test_post_run_http_error(mock_http_client):
+    """Test handling of HTTP errors."""
+    mock_response = Mock()
+    mock_response.status_code = 500
+    mock_response.text = "Internal Server Error"
+
+    def raise_http_error():
+        raise httpx.HTTPStatusError("Server error", request=Mock(), response=mock_response)
+
+    mock_response_async = AsyncMock()
+    mock_response_async.raise_for_status = raise_http_error
+
+    mock_stream_context = AsyncMock()
+    mock_stream_context.__aenter__.return_value = mock_response_async
+    mock_stream_context.__aexit__.return_value = None
+    mock_http_client.stream.return_value = mock_stream_context
+
+    service = AGUIHttpService("http://localhost:8888/", http_client=mock_http_client)
+
+    with pytest.raises(httpx.HTTPStatusError):
+        async for _ in service.post_run(thread_id="thread_123", run_id="run_456", messages=[]):
+            pass
+
+
+async def test_post_run_invalid_json(mock_http_client):
+    """Test handling of invalid JSON in SSE stream."""
+    invalid_sse = "data: {invalid json}\n\ndata: " + json.dumps({"type": "RUN_FINISHED"}) + "\n"
+
+    async def mock_aiter_lines():
+        for line in invalid_sse.split("\n"):
+            if line:
+                yield line
+
+    mock_response = AsyncMock()
+    mock_response.status_code = 200
+    mock_response.aiter_lines = mock_aiter_lines
+
+    mock_stream_context = AsyncMock()
+    mock_stream_context.__aenter__.return_value = mock_response
+    mock_stream_context.__aexit__.return_value = None
+    mock_http_client.stream.return_value = mock_stream_context
+
+    service = AGUIHttpService("http://localhost:8888/", http_client=mock_http_client)
+
+    events = []
+    async for event in service.post_run(thread_id="thread_123", run_id="run_456", messages=[]):
+        events.append(event)
+
+    # Should skip invalid JSON and continue with valid events
+    assert len(events) == 1
+    assert events[0]["type"] == "RUN_FINISHED"
+
+
+async def test_context_manager():
+    """Test context manager functionality."""
+    async with AGUIHttpService("http://localhost:8888/") as service:
+        assert service.http_client is not None
+        assert service._owns_client is True
+
+    # Client should be closed after exiting context
+
+
+async def test_context_manager_with_external_client():
+    """Test context manager doesn't close external client."""
+    external_client = httpx.AsyncClient()
+
+    async with AGUIHttpService("http://localhost:8888/", http_client=external_client) as service:
+        assert service.http_client is external_client
+        assert service._owns_client is False
+
+    # External client should still be open
+    # (caller's responsibility to close)
+    await external_client.aclose()
+
+
+async def test_post_run_empty_response(mock_http_client):
+    """Test handling of empty response stream."""
+
+    async def mock_aiter_lines():
+        return
+        yield  # Make it an async generator
+
+    mock_response = AsyncMock()
+    mock_response.status_code = 200
+    mock_response.aiter_lines = mock_aiter_lines
+
+    mock_stream_context = AsyncMock()
+    mock_stream_context.__aenter__.return_value = mock_response
+    mock_stream_context.__aexit__.return_value = None
+    mock_http_client.stream.return_value = mock_stream_context
+
+    service = AGUIHttpService("http://localhost:8888/", http_client=mock_http_client)
+
+    events = []
+    async for event in service.post_run(thread_id="thread_123", run_id="run_456", messages=[]):
+        events.append(event)
+
+    assert len(events) == 0
@@ -63,10 +63,9 @@ def test_agui_tool_result_to_agent_framework():
    assert isinstance(message.contents[0], TextContent)
    assert message.contents[0].text == '{"accepted": true, "steps": []}'

-    assert hasattr(message, "metadata")
-    assert message.metadata is not None
-    assert message.metadata.get("is_tool_result") is True
-    assert message.metadata.get("tool_call_id") == "call_123"
+    assert message.additional_properties is not None
+    assert message.additional_properties.get("is_tool_result") is True
+    assert message.additional_properties.get("tool_call_id") == "call_123"


 def test_agui_multiple_messages_to_agent_framework():
@@ -159,6 +158,36 @@ def test_agui_message_without_id():
    assert messages[0].message_id is None


+def test_agui_with_tool_calls_to_agent_framework():
+    """Assistant message with tool_calls is converted to FunctionCallContent."""
+    agui_msg = {
+        "role": "assistant",
+        "content": "Calling tool",
+        "tool_calls": [
+            {
+                "id": "call-123",
+                "type": "function",
+                "function": {"name": "get_weather", "arguments": {"location": "Seattle"}},
+            }
+        ],
+        "id": "msg-789",
+    }
+
+    messages = agui_messages_to_agent_framework([agui_msg])
+
+    assert len(messages) == 1
+    msg = messages[0]
+    assert msg.role == Role.ASSISTANT
+    assert msg.message_id == "msg-789"
+    # First content is text, second is the function call
+    assert isinstance(msg.contents[0], TextContent)
+    assert msg.contents[0].text == "Calling tool"
+    assert isinstance(msg.contents[1], FunctionCallContent)
+    assert msg.contents[1].call_id == "call-123"
+    assert msg.contents[1].name == "get_weather"
+    assert msg.contents[1].arguments == {"location": "Seattle"}
+
+
 def test_agent_framework_to_agui_with_tool_calls():
    """Test converting Agent Framework message with tool calls to AG-UI."""
    msg = ChatMessage(
@@ -198,13 +227,15 @@ def test_agent_framework_to_agui_multiple_text_contents():


 def test_agent_framework_to_agui_no_message_id():
-    """Test message without message_id."""
+    """Test message without message_id - should auto-generate ID."""
    msg = ChatMessage(role=Role.USER, contents=[TextContent(text="Hello")])

    messages = agent_framework_messages_to_agui([msg])

    assert len(messages) == 1
-    assert "id" not in messages[0]
+    assert "id" in messages[0]  # ID should be auto-generated
+    assert messages[0]["id"]  # ID should not be empty
+    assert len(messages[0]["id"]) > 0  # ID should be a valid string


 def test_agent_framework_to_agui_system_role():
@@ -0,0 +1,82 @@
+"""Tests for AG-UI orchestrators."""
+
+from collections.abc import AsyncGenerator
+from types import SimpleNamespace
+from typing import Any
+
+from agent_framework import AgentRunResponseUpdate, TextContent, ai_function
+from agent_framework._tools import FunctionInvocationConfiguration
+
+from agent_framework_ag_ui._agent import AgentConfig
+from agent_framework_ag_ui._orchestrators import DefaultOrchestrator, ExecutionContext
+
+
+@ai_function
+def server_tool() -> str:
+    """Server-executable tool."""
+    return "server"
+
+
+class DummyAgent:
+    """Minimal agent stub to capture run_stream parameters."""
+
+    def __init__(self) -> None:
+        self.chat_options = SimpleNamespace(tools=[server_tool], response_format=None)
+        self.tools = [server_tool]
+        self.chat_client = SimpleNamespace(
+            function_invocation_configuration=FunctionInvocationConfiguration(),
+        )
+        self.seen_tools: list[Any] | None = None
+
+    async def run_stream(
+        self,
+        messages: list[Any],
+        *,
+        thread: Any,
+        tools: list[Any] | None = None,
+    ) -> AsyncGenerator[AgentRunResponseUpdate, None]:
+        self.seen_tools = tools
+        yield AgentRunResponseUpdate(contents=[TextContent(text="ok")], role="assistant")
+
+
+async def test_default_orchestrator_merges_client_tools() -> None:
+    """Client tool declarations are merged with server tools before running agent."""
+
+    agent = DummyAgent()
+    orchestrator = DefaultOrchestrator()
+
+    input_data = {
+        "messages": [
+            {
+                "role": "user",
+                "content": [{"type": "input_text", "text": "Hello"}],
+            }
+        ],
+        "tools": [
+            {
+                "name": "get_weather",
+                "description": "Client weather lookup.",
+                "parameters": {
+                    "type": "object",
+                    "properties": {"location": {"type": "string"}},
+                    "required": ["location"],
+                },
+            }
+        ],
+    }
+
+    context = ExecutionContext(
+        input_data=input_data,
+        agent=agent,
+        config=AgentConfig(),
+    )
+
+    events = []
+    async for event in orchestrator.run(context):
+        events.append(event)
+
+    assert agent.seen_tools is not None
+    tool_names = [getattr(tool, "name", "?") for tool in agent.seen_tools]
+    assert "server_tool" in tool_names
+    assert "get_weather" in tool_names
+    assert agent.chat_client.function_invocation_configuration.additional_tools
@@ -197,3 +197,109 @@ def test_make_json_safe_fallback():
    result = make_json_safe(obj)
    # Objects with __dict__ return their __dict__ dict
    assert isinstance(result, dict)
+
+
+def test_convert_tools_to_agui_format_with_ai_function():
+    """Test converting AIFunction to AG-UI format."""
+    from agent_framework import ai_function
+
+    from agent_framework_ag_ui._utils import convert_tools_to_agui_format
+
+    @ai_function
+    def test_func(param: str, count: int = 5) -> str:
+        """Test function."""
+        return f"{param} {count}"
+
+    result = convert_tools_to_agui_format([test_func])
+
+    assert result is not None
+    assert len(result) == 1
+    assert result[0]["name"] == "test_func"
+    assert result[0]["description"] == "Test function."
+    assert "parameters" in result[0]
+    assert "properties" in result[0]["parameters"]
+
+
+def test_convert_tools_to_agui_format_with_callable():
+    """Test converting plain callable to AG-UI format."""
+    from agent_framework_ag_ui._utils import convert_tools_to_agui_format
+
+    def plain_func(x: int) -> int:
+        """A plain function."""
+        return x * 2
+
+    result = convert_tools_to_agui_format([plain_func])
+
+    assert result is not None
+    assert len(result) == 1
+    assert result[0]["name"] == "plain_func"
+    assert result[0]["description"] == "A plain function."
+    assert "parameters" in result[0]
+
+
+def test_convert_tools_to_agui_format_with_dict():
+    """Test converting dict tool to AG-UI format."""
+    from agent_framework_ag_ui._utils import convert_tools_to_agui_format
+
+    tool_dict = {
+        "name": "custom_tool",
+        "description": "Custom tool",
+        "parameters": {"type": "object"},
+    }
+
+    result = convert_tools_to_agui_format([tool_dict])
+
+    assert result is not None
+    assert len(result) == 1
+    assert result[0] == tool_dict
+
+
+def test_convert_tools_to_agui_format_with_none():
+    """Test converting None tools."""
+    from agent_framework_ag_ui._utils import convert_tools_to_agui_format
+
+    result = convert_tools_to_agui_format(None)
+
+    assert result is None
+
+
+def test_convert_tools_to_agui_format_with_single_tool():
+    """Test converting single tool (not in list)."""
+    from agent_framework import ai_function
+
+    from agent_framework_ag_ui._utils import convert_tools_to_agui_format
+
+    @ai_function
+    def single_tool(arg: str) -> str:
+        """Single tool."""
+        return arg
+
+    result = convert_tools_to_agui_format(single_tool)
+
+    assert result is not None
+    assert len(result) == 1
+    assert result[0]["name"] == "single_tool"
+
+
+def test_convert_tools_to_agui_format_with_multiple_tools():
+    """Test converting multiple tools."""
+    from agent_framework import ai_function
+
+    from agent_framework_ag_ui._utils import convert_tools_to_agui_format
+
+    @ai_function
+    def tool1(x: int) -> int:
+        """Tool 1."""
+        return x
+
+    @ai_function
+    def tool2(y: str) -> str:
+        """Tool 2."""
+        return y
+
+    result = convert_tools_to_agui_format([tool1, tool2])
+
+    assert result is not None
+    assert len(result) == 2
+    assert result[0]["name"] == "tool1"
+    assert result[1]["name"] == "tool2"
@@ -330,11 +330,19 @@ class AnthropicClient(BaseChatClient):
                    if content.has_top_level_media_type("image"):
                        a_content.append({
                            "type": "image",
-                            "source": {"data": content.uri, "media_type": content.media_type},
+                            "source": {
+                                "data": content.get_data_bytes_as_str(),
+                                "media_type": content.media_type,
+                                "type": "base64",
+                            },
                        })
+                    else:
+                        logger.debug(f"Ignoring unsupported data content media type: {content.media_type} for now")
                case "uri":
                    if content.has_top_level_media_type("image"):
                        a_content.append({"type": "image", "source": {"type": "url", "url": content.uri}})
+                    else:
+                        logger.debug(f"Ignoring unsupported data content media type: {content.media_type} for now")
                case "function_call":
                    a_content.append({
                        "type": "tool_use",
@@ -4,7 +4,7 @@ description = "Anthropic integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -1,5 +1,6 @@
 # Copyright (c) Microsoft. All rights reserved.
 import os
+from pathlib import Path
 from typing import Annotated
 from unittest.mock import MagicMock, patch

@@ -9,6 +10,7 @@ from agent_framework import (
    ChatMessage,
    ChatOptions,
    ChatResponseUpdate,
+    DataContent,
    FinishReason,
    FunctionCallContent,
    FunctionResultContent,
@@ -775,3 +777,31 @@ async def test_anthropic_client_integration_ordering() -> None:

    assert response is not None
    assert response.messages[0].text is not None
+
+
+@pytest.mark.flaky
+@skip_if_anthropic_integration_tests_disabled
+async def test_anthropic_client_integration_images() -> None:
+    """Integration test with images."""
+    client = AnthropicClient()
+
+    # get a image from the assets folder
+    image_path = Path(__file__).parent / "assets" / "sample_image.jpg"
+    with open(image_path, "rb") as img_file:  # noqa [ASYNC230]
+        image_bytes = img_file.read()
+
+    messages = [
+        ChatMessage(
+            role=Role.USER,
+            contents=[
+                TextContent(text="Describe this image"),
+                DataContent(media_type="image/jpeg", data=image_bytes),
+            ],
+        ),
+    ]
+
+    response = await client.get_response(messages=messages)
+
+    assert response is not None
+    assert response.messages[0].text is not None
+    assert "house" in response.messages[0].text.lower()
@@ -3,6 +3,7 @@
 import importlib.metadata

 from ._chat_client import AzureAIAgentClient
+from ._client import AzureAIClient
 from ._shared import AzureAISettings

 try:
@@ -12,6 +13,7 @@ except importlib.metadata.PackageNotFoundError:

 __all__ = [
    "AzureAIAgentClient",
+    "AzureAIClient",
    "AzureAISettings",
    "__version__",
 ]
@@ -0,0 +1,354 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import sys
+from collections.abc import MutableSequence
+from typing import Any, ClassVar, TypeVar
+
+from agent_framework import (
+    AGENT_FRAMEWORK_USER_AGENT,
+    ChatMessage,
+    ChatOptions,
+    HostedMCPTool,
+    TextContent,
+    get_logger,
+    use_chat_middleware,
+    use_function_invocation,
+)
+from agent_framework.exceptions import ServiceInitializationError
+from agent_framework.observability import use_observability
+from agent_framework.openai._responses_client import OpenAIBaseResponsesClient
+from azure.ai.projects.aio import AIProjectClient
+from azure.ai.projects.models import (
+    MCPTool,
+    PromptAgentDefinition,
+    PromptAgentDefinitionText,
+    ResponseTextFormatConfigurationJsonSchema,
+)
+from azure.core.credentials_async import AsyncTokenCredential
+from azure.core.exceptions import ResourceNotFoundError
+from openai.types.responses.parsed_response import (
+    ParsedResponse,
+)
+from openai.types.responses.response import Response as OpenAIResponse
+from pydantic import BaseModel, ValidationError
+
+from ._shared import AzureAISettings
+
+if sys.version_info >= (3, 11):
+    from typing import Self  # pragma: no cover
+else:
+    from typing_extensions import Self  # pragma: no cover
+
+
+logger = get_logger("agent_framework.azure")
+
+
+TAzureAIClient = TypeVar("TAzureAIClient", bound="AzureAIClient")
+
+
+@use_function_invocation
+@use_observability
+@use_chat_middleware
+class AzureAIClient(OpenAIBaseResponsesClient):
+    """Azure AI Agent client."""
+
+    OTEL_PROVIDER_NAME: ClassVar[str] = "azure.ai"  # type: ignore[reportIncompatibleVariableOverride, misc]
+
+    def __init__(
+        self,
+        *,
+        project_client: AIProjectClient | None = None,
+        agent_name: str | None = None,
+        agent_version: str | None = None,
+        conversation_id: str | None = None,
+        project_endpoint: str | None = None,
+        model_deployment_name: str | None = None,
+        async_credential: AsyncTokenCredential | None = None,
+        use_latest_version: bool | None = None,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize an Azure AI Agent client.
+
+        Keyword Args:
+            project_client: An existing AIProjectClient to use. If not provided, one will be created.
+            agent_name: The name to use when creating new agents.
+            agent_version: The version of the agent to use.
+            conversation_id: Default conversation ID to use for conversations. Can be overridden by
+                conversation_id property when making a request.
+            project_endpoint: The Azure AI Project endpoint URL.
+                Can also be set via environment variable AZURE_AI_PROJECT_ENDPOINT.
+                Ignored when a project_client is passed.
+            model_deployment_name: The model deployment name to use for agent creation.
+                Can also be set via environment variable AZURE_AI_MODEL_DEPLOYMENT_NAME.
+            async_credential: Azure async credential to use for authentication.
+            use_latest_version: Boolean flag that indicates whether to use latest agent version
+                if it exists in the service.
+            env_file_path: Path to environment file for loading settings.
+            env_file_encoding: Encoding of the environment file.
+            kwargs: Additional keyword arguments passed to the parent class.
+
+        Examples:
+            .. code-block:: python
+
+                from agent_framework.azure import AzureAIClient
+                from azure.identity.aio import DefaultAzureCredential
+
+                # Using environment variables
+                # Set AZURE_AI_PROJECT_ENDPOINT=https://your-project.cognitiveservices.azure.com
+                # Set AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4
+                credential = DefaultAzureCredential()
+                client = AzureAIClient(async_credential=credential)
+
+                # Or passing parameters directly
+                client = AzureAIClient(
+                    project_endpoint="https://your-project.cognitiveservices.azure.com",
+                    model_deployment_name="gpt-4",
+                    async_credential=credential,
+                )
+
+                # Or loading from a .env file
+                client = AzureAIClient(async_credential=credential, env_file_path="path/to/.env")
+        """
+        try:
+            azure_ai_settings = AzureAISettings(
+                project_endpoint=project_endpoint,
+                model_deployment_name=model_deployment_name,
+                env_file_path=env_file_path,
+                env_file_encoding=env_file_encoding,
+            )
+        except ValidationError as ex:
+            raise ServiceInitializationError("Failed to create Azure AI settings.", ex) from ex
+
+        # If no project_client is provided, create one
+        should_close_client = False
+        if project_client is None:
+            if not azure_ai_settings.project_endpoint:
+                raise ServiceInitializationError(
+                    "Azure AI project endpoint is required. Set via 'project_endpoint' parameter "
+                    "or 'AZURE_AI_PROJECT_ENDPOINT' environment variable."
+                )
+
+            # Use provided credential
+            if not async_credential:
+                raise ServiceInitializationError("Azure credential is required when project_client is not provided.")
+            project_client = AIProjectClient(
+                endpoint=azure_ai_settings.project_endpoint,
+                credential=async_credential,
+                user_agent=AGENT_FRAMEWORK_USER_AGENT,
+            )
+            should_close_client = True
+
+        # Initialize parent
+        super().__init__(
+            **kwargs,
+        )
+
+        # Initialize instance variables
+        self.agent_name = agent_name
+        self.agent_version = agent_version
+        self.use_latest_version = use_latest_version
+        self.project_client = project_client
+        self.credential = async_credential
+        self.model_id = azure_ai_settings.model_deployment_name
+        self.conversation_id = conversation_id
+        self._should_close_client = should_close_client  # Track whether we should close client connection
+
+    async def setup_azure_ai_observability(self, enable_sensitive_data: bool | None = None) -> None:
+        """Use this method to setup tracing in your Azure AI Project.
+
+        This will take the connection string from the project project_client.
+        It will override any connection string that is set in the environment variables.
+        It will disable any OTLP endpoint that might have been set.
+        """
+        try:
+            conn_string = await self.project_client.telemetry.get_application_insights_connection_string()
+        except ResourceNotFoundError:
+            logger.warning(
+                "No Application Insights connection string found for the Azure AI Project, "
+                "please call setup_observability() manually."
+            )
+            return
+        from agent_framework.observability import setup_observability
+
+        setup_observability(
+            applicationinsights_connection_string=conn_string, enable_sensitive_data=enable_sensitive_data
+        )
+
+    async def __aenter__(self) -> "Self":
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any) -> None:
+        """Async context manager exit."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the project_client."""
+        await self._close_client_if_needed()
+
+    async def _get_agent_reference_or_create(
+        self, run_options: dict[str, Any], messages_instructions: str | None
+    ) -> dict[str, str]:
+        """Determine which agent to use and create if needed.
+
+        Returns:
+            str: The agent_name to use
+        """
+        agent_name = self.agent_name or "UnnamedAgent"
+
+        # If no agent_version is provided, either use latest version or create a new agent:
+        if self.agent_version is None:
+            # Try to use latest version if requested and agent exists
+            if self.use_latest_version:
+                try:
+                    existing_agent = await self.project_client.agents.get(agent_name)
+                    self.agent_name = existing_agent.name
+                    self.agent_version = existing_agent.versions.latest.version
+                    return {"name": self.agent_name, "version": self.agent_version, "type": "agent_reference"}
+                except ResourceNotFoundError:
+                    # Agent doesn't exist, fall through to creation logic
+                    pass
+
+            if "model" not in run_options or not run_options["model"]:
+                raise ServiceInitializationError(
+                    "Model deployment name is required for agent creation, "
+                    "can also be passed to the get_response methods."
+                )
+
+            args: dict[str, Any] = {"model": run_options["model"]}
+
+            if "tools" in run_options:
+                args["tools"] = run_options["tools"]
+
+            if "response_format" in run_options:
+                response_format = run_options["response_format"]
+                args["text"] = PromptAgentDefinitionText(
+                    format=ResponseTextFormatConfigurationJsonSchema(
+                        name=response_format.__name__,
+                        schema=response_format.model_json_schema(),
+                    )
+                )
+
+            # Combine instructions from messages and options
+            combined_instructions = [
+                instructions
+                for instructions in [messages_instructions, run_options.get("instructions")]
+                if instructions
+            ]
+            if combined_instructions:
+                args["instructions"] = "".join(combined_instructions)
+
+            created_agent = await self.project_client.agents.create_version(
+                agent_name=agent_name, definition=PromptAgentDefinition(**args)
+            )
+
+            self.agent_name = created_agent.name
+            self.agent_version = created_agent.version
+
+        return {"name": agent_name, "version": self.agent_version, "type": "agent_reference"}
+
+    async def _close_client_if_needed(self) -> None:
+        """Close project_client session if we created it."""
+        if self._should_close_client:
+            await self.project_client.close()
+
+    def _prepare_input(self, messages: MutableSequence[ChatMessage]) -> tuple[list[ChatMessage], str | None]:
+        """Prepare input from messages and convert system/developer messages to instructions."""
+        result: list[ChatMessage] = []
+        instructions_list: list[str] = []
+        instructions: str | None = None
+
+        # System/developer messages are turned into instructions, since there is no such message roles in Azure AI.
+        for message in messages:
+            if message.role.value in ["system", "developer"]:
+                for text_content in [content for content in message.contents if isinstance(content, TextContent)]:
+                    instructions_list.append(text_content.text)
+            else:
+                result.append(message)
+
+        if len(instructions_list) > 0:
+            instructions = "".join(instructions_list)
+
+        return result, instructions
+
+    async def prepare_options(
+        self, messages: MutableSequence[ChatMessage], chat_options: ChatOptions
+    ) -> dict[str, Any]:
+        chat_options.store = bool(chat_options.store or chat_options.store is None)
+        prepared_messages, instructions = self._prepare_input(messages)
+        run_options = await super().prepare_options(prepared_messages, chat_options)
+        agent_reference = await self._get_agent_reference_or_create(run_options, instructions)
+
+        run_options["extra_body"] = {"agent": agent_reference}
+
+        conversation_id = chat_options.conversation_id or self.conversation_id
+
+        # Handle different conversation ID formats
+        if conversation_id:
+            if conversation_id.startswith("resp_"):
+                # For response IDs, set previous_response_id and remove conversation property
+                run_options.pop("conversation", None)
+                run_options["previous_response_id"] = conversation_id
+            elif conversation_id.startswith("conv_"):
+                # For conversation IDs, set conversation and remove previous_response_id property
+                run_options.pop("previous_response_id", None)
+                run_options["conversation"] = conversation_id
+
+        # Remove properties that are not supported on request level
+        # but were configured on agent level
+        exclude = ["model", "tools", "response_format"]
+
+        for property in exclude:
+            run_options.pop(property, None)
+
+        return run_options
+
+    async def initialize_client(self) -> None:
+        """Initialize OpenAI client asynchronously."""
+        self.client = await self.project_client.get_openai_client()  # type: ignore
+
+    def _update_agent_name(self, agent_name: str | None) -> None:
+        """Update the agent name in the chat client.
+
+        Args:
+            agent_name: The new name for the agent.
+        """
+        # This is a no-op in the base class, but can be overridden by subclasses
+        # to update the agent name in the client.
+        if agent_name and not self.agent_name:
+            self.agent_name = agent_name
+
+    def get_mcp_tool(self, tool: HostedMCPTool) -> Any:
+        """Get MCP tool from HostedMCPTool."""
+        mcp = MCPTool(server_label=tool.name.replace(" ", "_"), server_url=str(tool.url))
+
+        if tool.allowed_tools:
+            mcp["allowed_tools"] = list(tool.allowed_tools)
+
+        if tool.approval_mode:
+            match tool.approval_mode:
+                case str():
+                    mcp["require_approval"] = "always" if tool.approval_mode == "always_require" else "never"
+                case _:
+                    if always_require_approvals := tool.approval_mode.get("always_require_approval"):
+                        mcp["require_approval"] = {"always": {"tool_names": list(always_require_approvals)}}
+                    if never_require_approvals := tool.approval_mode.get("never_require_approval"):
+                        mcp["require_approval"] = {"never": {"tool_names": list(never_require_approvals)}}
+
+        return mcp
+
+    def get_conversation_id(
+        self, response: OpenAIResponse | ParsedResponse[BaseModel], store: bool | None
+    ) -> str | None:
+        """Get the conversation ID from the response if store is True."""
+        if store:
+            # If conversation ID exists, it means that we operate with conversation
+            # so we use conversation ID as input and output.
+            if response.conversation and response.conversation.id:
+                return response.conversation.id
+            # If conversation ID doesn't exist, we operate with responses
+            # so we use response ID as input and output.
+            return response.id
+        return None
@@ -4,7 +4,7 @@ description = "Azure AI Foundry integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -24,7 +24,7 @@ classifiers = [
 ]
 dependencies = [
    "agent-framework-core",
-    "azure-ai-projects >= 1.0.0b11",
+    "azure-ai-projects >= 2.0.0b1",
    "azure-ai-agents == 1.2.0b5",
    "aiohttp",
 ]
@@ -0,0 +1,743 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from agent_framework import (
+    ChatClientProtocol,
+    ChatMessage,
+    ChatOptions,
+    Role,
+    TextContent,
+)
+from agent_framework.exceptions import ServiceInitializationError
+from azure.ai.projects.models import (
+    ResponseTextFormatConfigurationJsonSchema,
+)
+from openai.types.responses.parsed_response import ParsedResponse
+from openai.types.responses.response import Response as OpenAIResponse
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from agent_framework_azure_ai import AzureAIClient, AzureAISettings
+
+
+def create_test_azure_ai_client(
+    mock_project_client: MagicMock,
+    agent_name: str | None = None,
+    agent_version: str | None = None,
+    conversation_id: str | None = None,
+    azure_ai_settings: AzureAISettings | None = None,
+    should_close_client: bool = False,
+    use_latest_version: bool | None = None,
+) -> AzureAIClient:
+    """Helper function to create AzureAIClient instances for testing, bypassing normal validation."""
+    if azure_ai_settings is None:
+        azure_ai_settings = AzureAISettings(env_file_path="test.env")
+
+    # Create client instance directly
+    client = object.__new__(AzureAIClient)
+
+    # Set attributes directly
+    client.project_client = mock_project_client
+    client.credential = None
+    client.agent_name = agent_name
+    client.agent_version = agent_version
+    client.use_latest_version = use_latest_version
+    client.model_id = azure_ai_settings.model_deployment_name
+    client.conversation_id = conversation_id
+    client._should_close_client = should_close_client  # type: ignore
+    client.additional_properties = {}
+    client.middleware = None
+
+    # Mock the OpenAI client attribute
+    mock_openai_client = MagicMock()
+    mock_openai_client.conversations = MagicMock()
+    mock_openai_client.conversations.create = AsyncMock()
+    client.client = mock_openai_client
+
+    return client
+
+
+def test_azure_ai_settings_init(azure_ai_unit_test_env: dict[str, str]) -> None:
+    """Test AzureAISettings initialization."""
+    settings = AzureAISettings()
+
+    assert settings.project_endpoint == azure_ai_unit_test_env["AZURE_AI_PROJECT_ENDPOINT"]
+    assert settings.model_deployment_name == azure_ai_unit_test_env["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
+
+
+def test_azure_ai_settings_init_with_explicit_values() -> None:
+    """Test AzureAISettings initialization with explicit values."""
+    settings = AzureAISettings(
+        project_endpoint="https://custom-endpoint.com/",
+        model_deployment_name="custom-model",
+    )
+
+    assert settings.project_endpoint == "https://custom-endpoint.com/"
+    assert settings.model_deployment_name == "custom-model"
+
+
+def test_azure_ai_client_init_with_project_client(mock_project_client: MagicMock) -> None:
+    """Test AzureAIClient initialization with existing project_client."""
+    with patch("agent_framework_azure_ai._client.AzureAISettings") as mock_settings:
+        mock_settings.return_value.project_endpoint = None
+        mock_settings.return_value.model_deployment_name = "test-model"
+
+        client = AzureAIClient(
+            project_client=mock_project_client,
+            agent_name="test-agent",
+            agent_version="1.0",
+        )
+
+        assert client.project_client is mock_project_client
+        assert client.agent_name == "test-agent"
+        assert client.agent_version == "1.0"
+        assert not client._should_close_client  # type: ignore
+        assert isinstance(client, ChatClientProtocol)
+
+
+def test_azure_ai_client_init_auto_create_client(
+    azure_ai_unit_test_env: dict[str, str],
+    mock_azure_credential: MagicMock,
+) -> None:
+    """Test AzureAIClient initialization with auto-created project_client."""
+    with patch("agent_framework_azure_ai._client.AIProjectClient") as mock_ai_project_client:
+        mock_project_client = MagicMock()
+        mock_ai_project_client.return_value = mock_project_client
+
+        client = AzureAIClient(
+            project_endpoint=azure_ai_unit_test_env["AZURE_AI_PROJECT_ENDPOINT"],
+            model_deployment_name=azure_ai_unit_test_env["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+            async_credential=mock_azure_credential,
+            agent_name="test-agent",
+        )
+
+        assert client.project_client is mock_project_client
+        assert client.agent_name == "test-agent"
+        assert client._should_close_client  # type: ignore
+
+        # Verify AIProjectClient was called with correct parameters
+        mock_ai_project_client.assert_called_once()
+
+
+def test_azure_ai_client_init_missing_project_endpoint() -> None:
+    """Test AzureAIClient initialization when project_endpoint is missing and no project_client provided."""
+    with patch("agent_framework_azure_ai._client.AzureAISettings") as mock_settings:
+        mock_settings.return_value.project_endpoint = None
+        mock_settings.return_value.model_deployment_name = "test-model"
+
+        with pytest.raises(ServiceInitializationError, match="Azure AI project endpoint is required"):
+            AzureAIClient(async_credential=MagicMock())
+
+
+def test_azure_ai_client_init_missing_credential(azure_ai_unit_test_env: dict[str, str]) -> None:
+    """Test AzureAIClient.__init__ when async_credential is missing and no project_client provided."""
+    with pytest.raises(
+        ServiceInitializationError, match="Azure credential is required when project_client is not provided"
+    ):
+        AzureAIClient(
+            project_endpoint=azure_ai_unit_test_env["AZURE_AI_PROJECT_ENDPOINT"],
+            model_deployment_name=azure_ai_unit_test_env["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
+        )
+
+
+def test_azure_ai_client_init_validation_error(mock_azure_credential: MagicMock) -> None:
+    """Test that ValidationError in AzureAISettings is properly handled."""
+    with patch("agent_framework_azure_ai._client.AzureAISettings") as mock_settings:
+        mock_settings.side_effect = ValidationError.from_exception_data("test", [])
+
+        with pytest.raises(ServiceInitializationError, match="Failed to create Azure AI settings"):
+            AzureAIClient(async_credential=mock_azure_credential)
+
+
+async def test_azure_ai_client_get_agent_reference_or_create_existing_version(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test _get_agent_reference_or_create when agent_version is already provided."""
+    client = create_test_azure_ai_client(mock_project_client, agent_name="existing-agent", agent_version="1.0")
+
+    agent_ref = await client._get_agent_reference_or_create({}, None)  # type: ignore
+
+    assert agent_ref == {"name": "existing-agent", "version": "1.0", "type": "agent_reference"}
+
+
+async def test_azure_ai_client_get_agent_reference_or_create_new_agent(
+    mock_project_client: MagicMock,
+    azure_ai_unit_test_env: dict[str, str],
+) -> None:
+    """Test _get_agent_reference_or_create when creating a new agent."""
+    azure_ai_settings = AzureAISettings(model_deployment_name=azure_ai_unit_test_env["AZURE_AI_MODEL_DEPLOYMENT_NAME"])
+    client = create_test_azure_ai_client(
+        mock_project_client, agent_name="new-agent", azure_ai_settings=azure_ai_settings
+    )
+
+    # Mock agent creation response
+    mock_agent = MagicMock()
+    mock_agent.name = "new-agent"
+    mock_agent.version = "1.0"
+    mock_project_client.agents.create_version = AsyncMock(return_value=mock_agent)
+
+    run_options = {"model": azure_ai_settings.model_deployment_name}
+    agent_ref = await client._get_agent_reference_or_create(run_options, None)  # type: ignore
+
+    assert agent_ref == {"name": "new-agent", "version": "1.0", "type": "agent_reference"}
+    assert client.agent_name == "new-agent"
+    assert client.agent_version == "1.0"
+
+
+async def test_azure_ai_client_get_agent_reference_missing_model(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test _get_agent_reference_or_create when model is missing for agent creation."""
+    client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent")
+
+    with pytest.raises(ServiceInitializationError, match="Model deployment name is required for agent creation"):
+        await client._get_agent_reference_or_create({}, None)  # type: ignore
+
+
+async def test_azure_ai_client_prepare_input_with_system_messages(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test _prepare_input converts system/developer messages to instructions."""
+    client = create_test_azure_ai_client(mock_project_client)
+
+    messages = [
+        ChatMessage(role=Role.SYSTEM, contents=[TextContent(text="You are a helpful assistant.")]),
+        ChatMessage(role=Role.USER, contents=[TextContent(text="Hello")]),
+        ChatMessage(role=Role.ASSISTANT, contents=[TextContent(text="System response")]),
+    ]
+
+    result_messages, instructions = client._prepare_input(messages)  # type: ignore
+
+    assert len(result_messages) == 2
+    assert result_messages[0].role == Role.USER
+    assert result_messages[1].role == Role.ASSISTANT
+    assert instructions == "You are a helpful assistant."
+
+
+async def test_azure_ai_client_prepare_input_no_system_messages(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test _prepare_input with no system/developer messages."""
+    client = create_test_azure_ai_client(mock_project_client)
+
+    messages = [
+        ChatMessage(role=Role.USER, contents=[TextContent(text="Hello")]),
+        ChatMessage(role=Role.ASSISTANT, contents=[TextContent(text="Hi there!")]),
+    ]
+
+    result_messages, instructions = client._prepare_input(messages)  # type: ignore
+
+    assert len(result_messages) == 2
+    assert instructions is None
+
+
+async def test_azure_ai_client_prepare_options_basic(mock_project_client: MagicMock) -> None:
+    """Test prepare_options basic functionality."""
+    client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent", agent_version="1.0")
+
+    messages = [ChatMessage(role=Role.USER, contents=[TextContent(text="Hello")])]
+    chat_options = ChatOptions()
+
+    with (
+        patch.object(client.__class__.__bases__[0], "prepare_options", return_value={"model": "test-model"}),
+        patch.object(
+            client,
+            "_get_agent_reference_or_create",
+            return_value={"name": "test-agent", "version": "1.0", "type": "agent_reference"},
+        ),
+    ):
+        run_options = await client.prepare_options(messages, chat_options)
+
+        assert "extra_body" in run_options
+        assert run_options["extra_body"]["agent"]["name"] == "test-agent"
+
+
+async def test_azure_ai_client_initialize_client(mock_project_client: MagicMock) -> None:
+    """Test initialize_client method."""
+    client = create_test_azure_ai_client(mock_project_client)
+
+    mock_openai_client = MagicMock()
+    mock_project_client.get_openai_client = AsyncMock(return_value=mock_openai_client)
+
+    await client.initialize_client()
+
+    assert client.client is mock_openai_client
+    mock_project_client.get_openai_client.assert_called_once()
+
+
+def test_azure_ai_client_update_agent_name(mock_project_client: MagicMock) -> None:
+    """Test _update_agent_name method."""
+    client = create_test_azure_ai_client(mock_project_client)
+
+    # Test updating agent name when current is None
+    with patch.object(client, "_update_agent_name") as mock_update:
+        mock_update.return_value = None
+        client._update_agent_name("new-agent")  # type: ignore
+        mock_update.assert_called_once_with("new-agent")
+
+    # Test behavior when agent name is updated
+    assert client.agent_name is None  # Should remain None since we didn't actually update
+    client.agent_name = "test-agent"  # Manually set for the test
+
+    # Test with None input
+    with patch.object(client, "_update_agent_name") as mock_update:
+        mock_update.return_value = None
+        client._update_agent_name(None)  # type: ignore
+        mock_update.assert_called_once_with(None)
+
+
+async def test_azure_ai_client_async_context_manager(mock_project_client: MagicMock) -> None:
+    """Test async context manager functionality."""
+    client = create_test_azure_ai_client(mock_project_client, should_close_client=True)
+
+    mock_project_client.close = AsyncMock()
+
+    async with client as ctx_client:
+        assert ctx_client is client
+
+    # Should call close after exiting context
+    mock_project_client.close.assert_called_once()
+
+
+async def test_azure_ai_client_close_method(mock_project_client: MagicMock) -> None:
+    """Test close method."""
+    client = create_test_azure_ai_client(mock_project_client, should_close_client=True)
+
+    mock_project_client.close = AsyncMock()
+
+    await client.close()
+
+    mock_project_client.close.assert_called_once()
+
+
+async def test_azure_ai_client_close_client_when_should_close_false(mock_project_client: MagicMock) -> None:
+    """Test _close_client_if_needed when should_close_client is False."""
+    client = create_test_azure_ai_client(mock_project_client, should_close_client=False)
+
+    mock_project_client.close = AsyncMock()
+
+    await client._close_client_if_needed()  # type: ignore
+
+    # Should not call close when should_close_client is False
+    mock_project_client.close.assert_not_called()
+
+
+async def test_azure_ai_client_agent_creation_with_instructions(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test agent creation with combined instructions."""
+    client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent")
+
+    # Mock agent creation response
+    mock_agent = MagicMock()
+    mock_agent.name = "test-agent"
+    mock_agent.version = "1.0"
+    mock_project_client.agents.create_version = AsyncMock(return_value=mock_agent)
+
+    run_options = {"model": "test-model", "instructions": "Option instructions. "}
+    messages_instructions = "Message instructions. "
+
+    await client._get_agent_reference_or_create(run_options, messages_instructions)  # type: ignore
+
+    # Verify agent was created with combined instructions
+    call_args = mock_project_client.agents.create_version.call_args
+    assert call_args[1]["definition"].instructions == "Message instructions. Option instructions. "
+
+
+async def test_azure_ai_client_agent_creation_with_tools(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test agent creation with tools."""
+    client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent")
+
+    # Mock agent creation response
+    mock_agent = MagicMock()
+    mock_agent.name = "test-agent"
+    mock_agent.version = "1.0"
+    mock_project_client.agents.create_version = AsyncMock(return_value=mock_agent)
+
+    test_tools = [{"type": "function", "function": {"name": "test_tool"}}]
+    run_options = {"model": "test-model", "tools": test_tools}
+
+    await client._get_agent_reference_or_create(run_options, None)  # type: ignore
+
+    # Verify agent was created with tools
+    call_args = mock_project_client.agents.create_version.call_args
+    assert call_args[1]["definition"].tools == test_tools
+
+
+async def test_azure_ai_client_use_latest_version_existing_agent(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test _get_agent_reference_or_create when use_latest_version=True and agent exists."""
+    client = create_test_azure_ai_client(mock_project_client, agent_name="existing-agent", use_latest_version=True)
+
+    # Mock existing agent response
+    mock_existing_agent = MagicMock()
+    mock_existing_agent.name = "existing-agent"
+    mock_existing_agent.versions.latest.version = "2.5"
+    mock_project_client.agents.get = AsyncMock(return_value=mock_existing_agent)
+
+    run_options = {"model": "test-model"}
+    agent_ref = await client._get_agent_reference_or_create(run_options, None)  # type: ignore
+
+    # Verify existing agent was retrieved and used
+    mock_project_client.agents.get.assert_called_once_with("existing-agent")
+    mock_project_client.agents.create_version.assert_not_called()
+
+    assert agent_ref == {"name": "existing-agent", "version": "2.5", "type": "agent_reference"}
+    assert client.agent_name == "existing-agent"
+    assert client.agent_version == "2.5"
+
+
+async def test_azure_ai_client_use_latest_version_agent_not_found(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test _get_agent_reference_or_create when use_latest_version=True but agent doesn't exist."""
+    from azure.core.exceptions import ResourceNotFoundError
+
+    client = create_test_azure_ai_client(mock_project_client, agent_name="non-existing-agent", use_latest_version=True)
+
+    # Mock ResourceNotFoundError when trying to retrieve agent
+    mock_project_client.agents.get = AsyncMock(side_effect=ResourceNotFoundError("Agent not found"))
+
+    # Mock agent creation response for fallback
+    mock_created_agent = MagicMock()
+    mock_created_agent.name = "non-existing-agent"
+    mock_created_agent.version = "1.0"
+    mock_project_client.agents.create_version = AsyncMock(return_value=mock_created_agent)
+
+    run_options = {"model": "test-model"}
+    agent_ref = await client._get_agent_reference_or_create(run_options, None)  # type: ignore
+
+    # Verify retrieval was attempted and creation was used as fallback
+    mock_project_client.agents.get.assert_called_once_with("non-existing-agent")
+    mock_project_client.agents.create_version.assert_called_once()
+
+    assert agent_ref == {"name": "non-existing-agent", "version": "1.0", "type": "agent_reference"}
+    assert client.agent_name == "non-existing-agent"
+    assert client.agent_version == "1.0"
+
+
+async def test_azure_ai_client_use_latest_version_false(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test _get_agent_reference_or_create when use_latest_version=False (default behavior)."""
+    client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent", use_latest_version=False)
+
+    # Mock agent creation response
+    mock_created_agent = MagicMock()
+    mock_created_agent.name = "test-agent"
+    mock_created_agent.version = "1.0"
+    mock_project_client.agents.create_version = AsyncMock(return_value=mock_created_agent)
+
+    run_options = {"model": "test-model"}
+    agent_ref = await client._get_agent_reference_or_create(run_options, None)  # type: ignore
+
+    # Verify retrieval was not attempted and creation was used directly
+    mock_project_client.agents.get.assert_not_called()
+    mock_project_client.agents.create_version.assert_called_once()
+
+    assert agent_ref == {"name": "test-agent", "version": "1.0", "type": "agent_reference"}
+
+
+async def test_azure_ai_client_use_latest_version_with_existing_agent_version(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test that use_latest_version is ignored when agent_version is already provided."""
+    client = create_test_azure_ai_client(
+        mock_project_client, agent_name="test-agent", agent_version="3.0", use_latest_version=True
+    )
+
+    agent_ref = await client._get_agent_reference_or_create({}, None)  # type: ignore
+
+    # Verify neither retrieval nor creation was attempted since version is already set
+    mock_project_client.agents.get.assert_not_called()
+    mock_project_client.agents.create_version.assert_not_called()
+
+    assert agent_ref == {"name": "test-agent", "version": "3.0", "type": "agent_reference"}
+
+
+class ResponseFormatModel(BaseModel):
+    """Test Pydantic model for response format testing."""
+
+    name: str
+    value: int
+    description: str
+    model_config = ConfigDict(extra="forbid")
+
+
+async def test_azure_ai_client_agent_creation_with_response_format(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test agent creation with response_format configuration."""
+    client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent")
+
+    # Mock agent creation response
+    mock_agent = MagicMock()
+    mock_agent.name = "test-agent"
+    mock_agent.version = "1.0"
+    mock_project_client.agents.create_version = AsyncMock(return_value=mock_agent)
+
+    run_options = {"model": "test-model", "response_format": ResponseFormatModel}
+
+    await client._get_agent_reference_or_create(run_options, None)  # type: ignore
+
+    # Verify agent was created with response format configuration
+    call_args = mock_project_client.agents.create_version.call_args
+    created_definition = call_args[1]["definition"]
+
+    # Check that text format configuration was set
+    assert hasattr(created_definition, "text")
+    assert created_definition.text is not None
+
+    # Check that the format is a ResponseTextFormatConfigurationJsonSchema
+    assert hasattr(created_definition.text, "format")
+    format_config = created_definition.text.format
+    assert isinstance(format_config, ResponseTextFormatConfigurationJsonSchema)
+
+    # Check the schema name matches the model class name
+    assert format_config.name == "ResponseFormatModel"
+
+    # Check that schema was generated correctly
+    assert format_config.schema is not None
+    schema = format_config.schema
+    assert "properties" in schema
+    assert "name" in schema["properties"]
+    assert "value" in schema["properties"]
+    assert "description" in schema["properties"]
+
+
+async def test_azure_ai_client_prepare_options_excludes_response_format(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test that prepare_options excludes response_format from final run options."""
+    client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent", agent_version="1.0")
+
+    messages = [ChatMessage(role=Role.USER, contents=[TextContent(text="Hello")])]
+    chat_options = ChatOptions()
+
+    with (
+        patch.object(
+            client.__class__.__bases__[0],
+            "prepare_options",
+            return_value={"model": "test-model", "response_format": ResponseFormatModel},
+        ),
+        patch.object(
+            client,
+            "_get_agent_reference_or_create",
+            return_value={"name": "test-agent", "version": "1.0", "type": "agent_reference"},
+        ),
+    ):
+        run_options = await client.prepare_options(messages, chat_options)
+
+        # response_format should be excluded from final run options
+        assert "response_format" not in run_options
+        # But extra_body should contain agent reference
+        assert "extra_body" in run_options
+        assert run_options["extra_body"]["agent"]["name"] == "test-agent"
+
+
+async def test_azure_ai_client_prepare_options_with_resp_conversation_id(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test prepare_options with conversation ID starting with 'resp_'."""
+    client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent", agent_version="1.0")
+
+    messages = [ChatMessage(role=Role.USER, contents=[TextContent(text="Hello")])]
+    chat_options = ChatOptions(conversation_id="resp_12345")
+
+    with (
+        patch.object(
+            client.__class__.__bases__[0],
+            "prepare_options",
+            return_value={"model": "test-model", "previous_response_id": "old_value", "conversation": "old_conv"},
+        ),
+        patch.object(
+            client,
+            "_get_agent_reference_or_create",
+            return_value={"name": "test-agent", "version": "1.0", "type": "agent_reference"},
+        ),
+    ):
+        run_options = await client.prepare_options(messages, chat_options)
+
+        # Should set previous_response_id and remove conversation property
+        assert run_options["previous_response_id"] == "resp_12345"
+        assert "conversation" not in run_options
+
+
+async def test_azure_ai_client_prepare_options_with_conv_conversation_id(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test prepare_options with conversation ID starting with 'conv_'."""
+    client = create_test_azure_ai_client(mock_project_client, agent_name="test-agent", agent_version="1.0")
+
+    messages = [ChatMessage(role=Role.USER, contents=[TextContent(text="Hello")])]
+    chat_options = ChatOptions(conversation_id="conv_67890")
+
+    with (
+        patch.object(
+            client.__class__.__bases__[0],
+            "prepare_options",
+            return_value={"model": "test-model", "previous_response_id": "old_value", "conversation": "old_conv"},
+        ),
+        patch.object(
+            client,
+            "_get_agent_reference_or_create",
+            return_value={"name": "test-agent", "version": "1.0", "type": "agent_reference"},
+        ),
+    ):
+        run_options = await client.prepare_options(messages, chat_options)
+
+        # Should set conversation and remove previous_response_id property
+        assert run_options["conversation"] == "conv_67890"
+        assert "previous_response_id" not in run_options
+
+
+async def test_azure_ai_client_prepare_options_with_client_conversation_id(
+    mock_project_client: MagicMock,
+) -> None:
+    """Test prepare_options using client's default conversation ID when chat options don't have one."""
+    client = create_test_azure_ai_client(
+        mock_project_client, agent_name="test-agent", agent_version="1.0", conversation_id="resp_client_default"
+    )
+
+    messages = [ChatMessage(role=Role.USER, contents=[TextContent(text="Hello")])]
+    chat_options = ChatOptions()  # No conversation_id specified
+
+    with (
+        patch.object(
+            client.__class__.__bases__[0],
+            "prepare_options",
+            return_value={"model": "test-model", "previous_response_id": "old_value", "conversation": "old_conv"},
+        ),
+        patch.object(
+            client,
+            "_get_agent_reference_or_create",
+            return_value={"name": "test-agent", "version": "1.0", "type": "agent_reference"},
+        ),
+    ):
+        run_options = await client.prepare_options(messages, chat_options)
+
+        # Should use client's default conversation_id and set previous_response_id
+        assert run_options["previous_response_id"] == "resp_client_default"
+        assert "conversation" not in run_options
+
+
+def test_get_conversation_id_with_store_true_and_conversation_id() -> None:
+    """Test get_conversation_id returns conversation ID when store is True and conversation exists."""
+    client = create_test_azure_ai_client(MagicMock())
+
+    # Mock OpenAI response with conversation
+    mock_response = MagicMock(spec=OpenAIResponse)
+    mock_response.id = "resp_12345"
+    mock_conversation = MagicMock()
+    mock_conversation.id = "conv_67890"
+    mock_response.conversation = mock_conversation
+
+    result = client.get_conversation_id(mock_response, store=True)
+
+    assert result == "conv_67890"
+
+
+def test_get_conversation_id_with_store_true_and_no_conversation() -> None:
+    """Test get_conversation_id returns response ID when store is True and no conversation exists."""
+    client = create_test_azure_ai_client(MagicMock())
+
+    # Mock OpenAI response without conversation
+    mock_response = MagicMock(spec=OpenAIResponse)
+    mock_response.id = "resp_12345"
+    mock_response.conversation = None
+
+    result = client.get_conversation_id(mock_response, store=True)
+
+    assert result == "resp_12345"
+
+
+def test_get_conversation_id_with_store_true_and_empty_conversation_id() -> None:
+    """Test get_conversation_id returns response ID when store is True and conversation ID is empty."""
+    client = create_test_azure_ai_client(MagicMock())
+
+    # Mock OpenAI response with conversation but empty ID
+    mock_response = MagicMock(spec=OpenAIResponse)
+    mock_response.id = "resp_12345"
+    mock_conversation = MagicMock()
+    mock_conversation.id = ""
+    mock_response.conversation = mock_conversation
+
+    result = client.get_conversation_id(mock_response, store=True)
+
+    assert result == "resp_12345"
+
+
+def test_get_conversation_id_with_store_false() -> None:
+    """Test get_conversation_id returns None when store is False."""
+    client = create_test_azure_ai_client(MagicMock())
+
+    # Mock OpenAI response with conversation
+    mock_response = MagicMock(spec=OpenAIResponse)
+    mock_response.id = "resp_12345"
+    mock_conversation = MagicMock()
+    mock_conversation.id = "conv_67890"
+    mock_response.conversation = mock_conversation
+
+    result = client.get_conversation_id(mock_response, store=False)
+
+    assert result is None
+
+
+def test_get_conversation_id_with_parsed_response_and_store_true() -> None:
+    """Test get_conversation_id works with ParsedResponse when store is True."""
+    client = create_test_azure_ai_client(MagicMock())
+
+    # Mock ParsedResponse with conversation
+    mock_response = MagicMock(spec=ParsedResponse[BaseModel])
+    mock_response.id = "resp_parsed_12345"
+    mock_conversation = MagicMock()
+    mock_conversation.id = "conv_parsed_67890"
+    mock_response.conversation = mock_conversation
+
+    result = client.get_conversation_id(mock_response, store=True)
+
+    assert result == "conv_parsed_67890"
+
+
+def test_get_conversation_id_with_parsed_response_no_conversation() -> None:
+    """Test get_conversation_id returns response ID with ParsedResponse when no conversation exists."""
+    client = create_test_azure_ai_client(MagicMock())
+
+    # Mock ParsedResponse without conversation
+    mock_response = MagicMock(spec=ParsedResponse[BaseModel])
+    mock_response.id = "resp_parsed_12345"
+    mock_response.conversation = None
+
+    result = client.get_conversation_id(mock_response, store=True)
+
+    assert result == "resp_parsed_12345"
+
+
+@pytest.fixture
+def mock_project_client() -> MagicMock:
+    """Fixture that provides a mock AIProjectClient."""
+    mock_client = MagicMock()
+
+    # Mock agents property
+    mock_client.agents = MagicMock()
+    mock_client.agents.create_version = AsyncMock()
+
+    # Mock conversations property
+    mock_client.conversations = MagicMock()
+    mock_client.conversations.create = AsyncMock()
+
+    # Mock telemetry property
+    mock_client.telemetry = MagicMock()
+    mock_client.telemetry.get_application_insights_connection_string = AsyncMock()
+
+    # Mock get_openai_client method
+    mock_client.get_openai_client = AsyncMock()
+
+    # Mock close method
+    mock_client.close = AsyncMock()
+
+    return mock_client
@@ -4,7 +4,7 @@ description = "OpenAI ChatKit integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -4,7 +4,7 @@ description = "Copilot Studio integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -564,10 +564,6 @@ class BaseChatClient(SerializationMixin, ABC):

        # Validate that store is True when conversation_id is set
        if chat_options.conversation_id is not None and chat_options.store is not True:
-            logger.warning(
-                "When conversation_id is set, store must be True for service-managed threads. "
-                "Automatically setting store=True."
-            )
            chat_options.store = True

        if chat_options.instructions:
@@ -663,10 +659,6 @@ class BaseChatClient(SerializationMixin, ABC):

        # Validate that store is True when conversation_id is set
        if chat_options.conversation_id is not None and chat_options.store is not True:
-            logger.warning(
-                "When conversation_id is set, store must be True for service-managed threads. "
-                "Automatically setting store=True."
-            )
            chat_options.store = True

        if chat_options.instructions:
@@ -19,7 +19,7 @@ from mcp.client.websocket import websocket_client
 from mcp.shared.context import RequestContext
 from mcp.shared.exceptions import McpError
 from mcp.shared.session import RequestResponder
-from pydantic import BaseModel, create_model
+from pydantic import BaseModel, Field, create_model

 from ._tools import AIFunction, HostedMCPSpecificApproval
 from ._types import ChatMessage, Contents, DataContent, Role, TextContent, UriContent
@@ -224,13 +224,20 @@ def _get_input_model_from_mcp_tool(tool: types.Tool) -> type[BaseModel]:
        prop_details = json.loads(prop_details) if isinstance(prop_details, str) else prop_details

        python_type = resolve_type(prop_details)
+        description = prop_details.get("description", "")

        # Create field definition for create_model
        if prop_name in required:
-            field_definitions[prop_name] = (python_type, ...)
+            field_definitions[prop_name] = (
+                (python_type, Field(description=description)) if description else (python_type, ...)
+            )
        else:
            default_value = prop_details.get("default", None)
-            field_definitions[prop_name] = (python_type, default_value)
+            field_definitions[prop_name] = (
+                (python_type, Field(default=default_value, description=description))
+                if description
+                else (python_type, default_value)
+            )

    return create_model(f"{tool.name}_input", **field_definitions)

@@ -1636,7 +1636,7 @@ def _handle_function_calls_response(
                    # this runs in every but the first run
                    # we need to keep track of all function call messages
                    fcc_messages.extend(response.messages)
-                    if getattr(kwargs.get("chat_options"), "store", False):
+                    if response.conversation_id is not None:
                        prepped_messages.clear()
                        prepped_messages.append(result_message)
                    else:
@@ -1839,7 +1839,7 @@ def _handle_function_calls_streaming_response(
                    # this runs in every but the first run
                    # we need to keep track of all function call messages
                    fcc_messages.extend(response.messages)
-                    if getattr(kwargs.get("chat_options"), "store", False):
+                    if response.conversation_id is not None:
                        prepped_messages.clear()
                        prepped_messages.append(result_message)
                    else:
@@ -897,6 +897,9 @@ class TextReasoningContent(BaseContent):
        return self


+TDataContent = TypeVar("TDataContent", bound="DataContent")
+
+
 class DataContent(BaseContent):
    """Represents binary data content with an associated media type (also known as a MIME type).

@@ -1050,6 +1053,70 @@ class DataContent(BaseContent):
    def has_top_level_media_type(self, top_level_media_type: Literal["application", "audio", "image", "text"]) -> bool:
        return _has_top_level_media_type(self.media_type, top_level_media_type)

+    @staticmethod
+    def detect_image_format_from_base64(image_base64: str) -> str:
+        """Detect image format from base64 data by examining the binary header.
+
+        Args:
+            image_base64: Base64 encoded image data
+
+        Returns:
+            Image format as string (png, jpeg, webp, gif) with png as fallback
+        """
+        try:
+            # Constants for image format detection
+            # ~75 bytes of binary data should be enough to detect most image formats
+            FORMAT_DETECTION_BASE64_CHARS = 100
+
+            # Decode a small portion to detect format
+            decoded_data = base64.b64decode(image_base64[:FORMAT_DETECTION_BASE64_CHARS])
+            if decoded_data.startswith(b"\x89PNG"):
+                return "png"
+            if decoded_data.startswith(b"\xff\xd8\xff"):
+                return "jpeg"
+            if decoded_data.startswith(b"RIFF") and b"WEBP" in decoded_data[:12]:
+                return "webp"
+            if decoded_data.startswith(b"GIF87a") or decoded_data.startswith(b"GIF89a"):
+                return "gif"
+            return "png"  # Default fallback
+        except Exception:
+            return "png"  # Fallback if decoding fails
+
+    @staticmethod
+    def create_data_uri_from_base64(image_base64: str) -> tuple[str, str]:
+        """Create a data URI and media type from base64 image data.
+
+        Args:
+            image_base64: Base64 encoded image data
+
+        Returns:
+            Tuple of (data_uri, media_type)
+        """
+        format_type = DataContent.detect_image_format_from_base64(image_base64)
+        uri = f"data:image/{format_type};base64,{image_base64}"
+        media_type = f"image/{format_type}"
+        return uri, media_type
+
+    def get_data_bytes_as_str(self) -> str:
+        """Extracts and returns the base64-encoded data from the data URI.
+
+        Returns:
+            The binary data as str.
+        """
+        match = URI_PATTERN.match(self.uri)
+        if not match:
+            raise ValueError(f"Invalid data URI format: {self.uri}")
+        return match.group("base64_data")
+
+    def get_data_bytes(self) -> bytes:
+        """Extracts and returns the binary data from the data URI.
+
+        Returns:
+            The binary data as bytes.
+        """
+        base64_data = self.get_data_bytes_as_str()
+        return base64.b64decode(base64_data)
+

 class UriContent(BaseContent):
    """Represents a URI content.
@@ -2,11 +2,14 @@

 import logging
 from dataclasses import dataclass
-from typing import Any
+from typing import Any, cast
+
+from agent_framework import FunctionApprovalRequestContent, FunctionApprovalResponseContent

 from .._agents import AgentProtocol, ChatAgent
 from .._threads import AgentThread
 from .._types import AgentRunResponse, AgentRunResponseUpdate, ChatMessage
+from ._checkpoint_encoding import decode_checkpoint_value, encode_checkpoint_value
 from ._conversation_state import encode_chat_messages
 from ._events import (
    AgentRunEvent,
@@ -14,6 +17,7 @@ from ._events import (
 )
 from ._executor import Executor, handler
 from ._message_utils import normalize_messages_input
+from ._request_info_mixin import response_handler
 from ._workflow_context import WorkflowContext

 logger = logging.getLogger(__name__)
@@ -83,6 +87,8 @@ class AgentExecutor(Executor):
        super().__init__(exec_id)
        self._agent = agent
        self._agent_thread = agent_thread or self._agent.get_new_thread()
+        self._pending_agent_requests: dict[str, FunctionApprovalRequestContent] = {}
+        self._pending_responses_to_agent: list[FunctionApprovalResponseContent] = []
        self._output_response = output_response
        self._cache: list[ChatMessage] = []

@@ -93,50 +99,6 @@ class AgentExecutor(Executor):
            return [AgentRunResponse]
        return []

-    async def _run_agent_and_emit(self, ctx: WorkflowContext[AgentExecutorResponse, AgentRunResponse]) -> None:
-        """Execute the underlying agent, emit events, and enqueue response.
-
-        Checks ctx.is_streaming() to determine whether to emit incremental AgentRunUpdateEvent
-        events (streaming mode) or a single AgentRunEvent (non-streaming mode).
-        """
-        if ctx.is_streaming():
-            # Streaming mode: emit incremental updates
-            updates: list[AgentRunResponseUpdate] = []
-            async for update in self._agent.run_stream(
-                self._cache,
-                thread=self._agent_thread,
-            ):
-                updates.append(update)
-                await ctx.add_event(AgentRunUpdateEvent(self.id, update))
-
-            if isinstance(self._agent, ChatAgent):
-                response_format = self._agent.chat_options.response_format
-                response = AgentRunResponse.from_agent_run_response_updates(
-                    updates,
-                    output_format_type=response_format,
-                )
-            else:
-                response = AgentRunResponse.from_agent_run_response_updates(updates)
-        else:
-            # Non-streaming mode: use run() and emit single event
-            response = await self._agent.run(
-                self._cache,
-                thread=self._agent_thread,
-            )
-            await ctx.add_event(AgentRunEvent(self.id, response))
-
-        if self._output_response:
-            await ctx.yield_output(response)
-
-        # Always construct a full conversation snapshot from inputs (cache)
-        # plus agent outputs (agent_run_response.messages). Do not mutate
-        # response.messages so AgentRunEvent remains faithful to the raw output.
-        full_conversation: list[ChatMessage] = list(self._cache) + list(response.messages)
-
-        agent_response = AgentExecutorResponse(self.id, response, full_conversation=full_conversation)
-        await ctx.send_message(agent_response)
-        self._cache.clear()
-
    @handler
    async def run(
        self, request: AgentExecutorRequest, ctx: WorkflowContext[AgentExecutorResponse, AgentRunResponse]
@@ -192,6 +154,31 @@ class AgentExecutor(Executor):
        self._cache = normalize_messages_input(messages)
        await self._run_agent_and_emit(ctx)

+    @response_handler
+    async def handle_user_input_response(
+        self,
+        original_request: FunctionApprovalRequestContent,
+        response: FunctionApprovalResponseContent,
+        ctx: WorkflowContext[AgentExecutorResponse, AgentRunResponse],
+    ) -> None:
+        """Handle user input responses for function approvals during agent execution.
+
+        This will hold the executor's execution until all pending user input requests are resolved.
+
+        Args:
+            original_request: The original function approval request sent by the agent.
+            response: The user's response to the function approval request.
+            ctx: The workflow context for emitting events and outputs.
+        """
+        self._pending_responses_to_agent.append(response)
+        self._pending_agent_requests.pop(original_request.id, None)
+
+        if not self._pending_agent_requests:
+            # All pending requests have been resolved; resume agent execution
+            self._cache = normalize_messages_input(ChatMessage(role="user", contents=self._pending_responses_to_agent))
+            self._pending_responses_to_agent.clear()
+            await self._run_agent_and_emit(ctx)
+
    async def snapshot_state(self) -> dict[str, Any]:
        """Capture current executor state for checkpointing.

@@ -226,6 +213,8 @@ class AgentExecutor(Executor):
        return {
            "cache": encode_chat_messages(self._cache),
            "agent_thread": serialized_thread,
+            "pending_agent_requests": encode_checkpoint_value(self._pending_agent_requests),
+            "pending_responses_to_agent": encode_checkpoint_value(self._pending_responses_to_agent),
        }

    async def restore_state(self, state: dict[str, Any]) -> None:
@@ -258,7 +247,109 @@ class AgentExecutor(Executor):
        else:
            self._agent_thread = self._agent.get_new_thread()

+        pending_requests_payload = state.get("pending_agent_requests")
+        if pending_requests_payload:
+            self._pending_agent_requests = decode_checkpoint_value(pending_requests_payload)
+
+        pending_responses_payload = state.get("pending_responses_to_agent")
+        if pending_responses_payload:
+            self._pending_responses_to_agent = decode_checkpoint_value(pending_responses_payload)
+
    def reset(self) -> None:
        """Reset the internal cache of the executor."""
        logger.debug("AgentExecutor %s: Resetting cache", self.id)
        self._cache.clear()
+
+    async def _run_agent_and_emit(self, ctx: WorkflowContext[AgentExecutorResponse, AgentRunResponse]) -> None:
+        """Execute the underlying agent, emit events, and enqueue response.
+
+        Checks ctx.is_streaming() to determine whether to emit incremental AgentRunUpdateEvent
+        events (streaming mode) or a single AgentRunEvent (non-streaming mode).
+        """
+        if ctx.is_streaming():
+            # Streaming mode: emit incremental updates
+            response = await self._run_agent_streaming(cast(WorkflowContext, ctx))
+        else:
+            # Non-streaming mode: use run() and emit single event
+            response = await self._run_agent(cast(WorkflowContext, ctx))
+
+        if response is None:
+            # Agent did not complete (e.g., waiting for user input); do not emit response
+            logger.info("AgentExecutor %s: Agent did not complete, awaiting user input", self.id)
+            return
+
+        if self._output_response:
+            await ctx.yield_output(response)
+
+        # Always construct a full conversation snapshot from inputs (cache)
+        # plus agent outputs (agent_run_response.messages). Do not mutate
+        # response.messages so AgentRunEvent remains faithful to the raw output.
+        full_conversation: list[ChatMessage] = list(self._cache) + list(response.messages)
+
+        agent_response = AgentExecutorResponse(self.id, response, full_conversation=full_conversation)
+        await ctx.send_message(agent_response)
+        self._cache.clear()
+
+    async def _run_agent(self, ctx: WorkflowContext) -> AgentRunResponse | None:
+        """Execute the underlying agent in non-streaming mode.
+
+        Args:
+            ctx: The workflow context for emitting events.
+
+        Returns:
+            The complete AgentRunResponse, or None if waiting for user input.
+        """
+        response = await self._agent.run(
+            self._cache,
+            thread=self._agent_thread,
+        )
+        await ctx.add_event(AgentRunEvent(self.id, response))
+
+        # Handle any user input requests
+        if response.user_input_requests:
+            for user_input_request in response.user_input_requests:
+                self._pending_agent_requests[user_input_request.id] = user_input_request
+                await ctx.request_info(user_input_request, FunctionApprovalResponseContent)
+            return None
+
+        return response
+
+    async def _run_agent_streaming(self, ctx: WorkflowContext) -> AgentRunResponse | None:
+        """Execute the underlying agent in streaming mode and collect the full response.
+
+        Args:
+            ctx: The workflow context for emitting events.
+
+        Returns:
+            The complete AgentRunResponse, or None if waiting for user input.
+        """
+        updates: list[AgentRunResponseUpdate] = []
+        user_input_requests: list[FunctionApprovalRequestContent] = []
+        async for update in self._agent.run_stream(
+            self._cache,
+            thread=self._agent_thread,
+        ):
+            updates.append(update)
+            await ctx.add_event(AgentRunUpdateEvent(self.id, update))
+
+            if update.user_input_requests:
+                user_input_requests.extend(update.user_input_requests)
+
+        # Build the final AgentRunResponse from the collected updates
+        if isinstance(self._agent, ChatAgent):
+            response_format = self._agent.chat_options.response_format
+            response = AgentRunResponse.from_agent_run_response_updates(
+                updates,
+                output_format_type=response_format,
+            )
+        else:
+            response = AgentRunResponse.from_agent_run_response_updates(updates)
+
+        # Handle any user input requests after the streaming completes
+        if user_input_requests:
+            for user_input_request in user_input_requests:
+                self._pending_agent_requests[user_input_request.id] = user_input_request
+                await ctx.request_info(user_input_request, FunctionApprovalResponseContent)
+            return None
+
+        return response
@@ -0,0 +1,35 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib
+from typing import Any
+
+PACKAGE_NAME = "agent_framework_ag_ui"
+PACKAGE_EXTRA = "ag-ui"
+_IMPORTS = [
+    "__version__",
+    "AgentFrameworkAgent",
+    "add_agent_framework_fastapi_endpoint",
+    "AGUIChatClient",
+    "AGUIEventConverter",
+    "AGUIHttpService",
+    "ConfirmationStrategy",
+    "DefaultConfirmationStrategy",
+    "TaskPlannerConfirmationStrategy",
+    "RecipeConfirmationStrategy",
+    "DocumentWriterConfirmationStrategy",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name in _IMPORTS:
+        try:
+            return getattr(importlib.import_module(PACKAGE_NAME), name)
+        except ModuleNotFoundError as exc:
+            raise ModuleNotFoundError(
+                f"The '{PACKAGE_EXTRA}' extra is not installed, please do `pip install agent-framework-{PACKAGE_EXTRA}`"
+            ) from exc
+    raise AttributeError(f"Module {PACKAGE_NAME} has no attribute {name}.")
+
+
+def __dir__() -> list[str]:
+    return _IMPORTS
@@ -0,0 +1,29 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from agent_framework_ag_ui import (
+    AgentFrameworkAgent,
+    AGUIChatClient,
+    AGUIEventConverter,
+    AGUIHttpService,
+    ConfirmationStrategy,
+    DefaultConfirmationStrategy,
+    DocumentWriterConfirmationStrategy,
+    RecipeConfirmationStrategy,
+    TaskPlannerConfirmationStrategy,
+    __version__,
+    add_agent_framework_fastapi_endpoint,
+)
+
+__all__ = [
+    "AGUIChatClient",
+    "AGUIEventConverter",
+    "AGUIHttpService",
+    "AgentFrameworkAgent",
+    "ConfirmationStrategy",
+    "DefaultConfirmationStrategy",
+    "DocumentWriterConfirmationStrategy",
+    "RecipeConfirmationStrategy",
+    "TaskPlannerConfirmationStrategy",
+    "__version__",
+    "add_agent_framework_fastapi_endpoint",
+]
@@ -6,6 +6,7 @@ from typing import Any

 _IMPORTS: dict[str, tuple[str, str]] = {
    "AzureAIAgentClient": ("agent_framework_azure_ai", "azure-ai"),
+    "AzureAIClient": ("agent_framework_azure_ai", "azure-ai"),
    "AzureOpenAIAssistantsClient": ("agent_framework.azure._assistants_client", "core"),
    "AzureOpenAIChatClient": ("agent_framework.azure._chat_client", "core"),
    "AzureAISettings": ("agent_framework_azure_ai", "azure-ai"),
@@ -1,6 +1,6 @@
 # Copyright (c) Microsoft. All rights reserved.

-from agent_framework_azure_ai import AzureAIAgentClient, AzureAISettings
+from agent_framework_azure_ai import AzureAIAgentClient, AzureAIClient, AzureAISettings

 from agent_framework.azure._assistants_client import AzureOpenAIAssistantsClient
 from agent_framework.azure._chat_client import AzureOpenAIChatClient
@@ -10,6 +10,7 @@ from agent_framework.azure._shared import AzureOpenAISettings

 __all__ = [
    "AzureAIAgentClient",
+    "AzureAIClient",
    "AzureAISettings",
    "AzureOpenAIAssistantsClient",
    "AzureOpenAIChatClient",
@@ -161,7 +161,8 @@ class OpenAIAssistantsClient(OpenAIConfigMixin, BaseChatClient):
    async def close(self) -> None:
        """Clean up any assistants we created."""
        if self._should_delete_assistant and self.assistant_id is not None:
-            await self.client.beta.assistants.delete(self.assistant_id)
+            client = await self.ensure_client()
+            await client.beta.assistants.delete(self.assistant_id)
            object.__setattr__(self, "assistant_id", None)
            object.__setattr__(self, "_should_delete_assistant", False)

@@ -215,7 +216,11 @@ class OpenAIAssistantsClient(OpenAIConfigMixin, BaseChatClient):
        """
        # If no assistant is provided, create a temporary assistant
        if self.assistant_id is None:
-            created_assistant = await self.client.beta.assistants.create(name=self.assistant_name, model=self.model_id)
+            if not self.model_id:
+                raise ServiceInitializationError("Parameter 'model_id' is required for assistant creation.")
+
+            client = await self.ensure_client()
+            created_assistant = await client.beta.assistants.create(name=self.assistant_name, model=self.model_id)
            self.assistant_id = created_assistant.id
            self._should_delete_assistant = True

@@ -233,6 +238,7 @@ class OpenAIAssistantsClient(OpenAIConfigMixin, BaseChatClient):
        Returns:
            tuple: (stream, final_thread_id)
        """
+        client = await self.ensure_client()
        # Get any active run for this thread
        thread_run = await self._get_active_thread_run(thread_id)

@@ -240,7 +246,7 @@ class OpenAIAssistantsClient(OpenAIConfigMixin, BaseChatClient):

        if thread_run is not None and tool_run_id is not None and tool_run_id == thread_run.id and tool_outputs:
            # There's an active run and we have tool results to submit, so submit the results.
-            stream = self.client.beta.threads.runs.submit_tool_outputs_stream(  # type: ignore[reportDeprecated]
+            stream = client.beta.threads.runs.submit_tool_outputs_stream(  # type: ignore[reportDeprecated]
                run_id=tool_run_id, thread_id=thread_run.thread_id, tool_outputs=tool_outputs
            )
            final_thread_id = thread_run.thread_id
@@ -249,7 +255,7 @@ class OpenAIAssistantsClient(OpenAIConfigMixin, BaseChatClient):
            final_thread_id = await self._prepare_thread(thread_id, thread_run, run_options)

            # Now create a new run and stream the results.
-            stream = self.client.beta.threads.runs.stream(  # type: ignore[reportDeprecated]
+            stream = client.beta.threads.runs.stream(  # type: ignore[reportDeprecated]
                assistant_id=assistant_id, thread_id=final_thread_id, **run_options
            )

@@ -257,19 +263,21 @@ class OpenAIAssistantsClient(OpenAIConfigMixin, BaseChatClient):

    async def _get_active_thread_run(self, thread_id: str | None) -> Run | None:
        """Get any active run for the given thread."""
+        client = await self.ensure_client()
        if thread_id is None:
            return None

-        async for run in self.client.beta.threads.runs.list(thread_id=thread_id, limit=1, order="desc"):  # type: ignore[reportDeprecated]
+        async for run in client.beta.threads.runs.list(thread_id=thread_id, limit=1, order="desc"):  # type: ignore[reportDeprecated]
            if run.status not in ["completed", "cancelled", "failed", "expired"]:
                return run
        return None

    async def _prepare_thread(self, thread_id: str | None, thread_run: Run | None, run_options: dict[str, Any]) -> str:
        """Prepare the thread for a new run, creating or cleaning up as needed."""
+        client = await self.ensure_client()
        if thread_id is None:
            # No thread ID was provided, so create a new thread.
-            thread = await self.client.beta.threads.create(  # type: ignore[reportDeprecated]
+            thread = await client.beta.threads.create(  # type: ignore[reportDeprecated]
                messages=run_options["additional_messages"],
                tool_resources=run_options.get("tool_resources"),
                metadata=run_options.get("metadata"),
@@ -280,7 +288,7 @@ class OpenAIAssistantsClient(OpenAIConfigMixin, BaseChatClient):

        if thread_run is not None:
            # There was an active run; we need to cancel it before starting a new run.
-            await self.client.beta.threads.runs.cancel(run_id=thread_run.id, thread_id=thread_id)  # type: ignore[reportDeprecated]
+            await client.beta.threads.runs.cancel(run_id=thread_run.id, thread_id=thread_id)  # type: ignore[reportDeprecated]

        return thread_id

@@ -69,10 +69,11 @@ class OpenAIBaseChatClient(OpenAIBase, BaseChatClient):
        chat_options: ChatOptions,
        **kwargs: Any,
    ) -> ChatResponse:
+        client = await self.ensure_client()
        options_dict = self._prepare_options(messages, chat_options)
        try:
            return self._create_chat_response(
-                await self.client.chat.completions.create(stream=False, **options_dict), chat_options
+                await client.chat.completions.create(stream=False, **options_dict), chat_options
            )
        except BadRequestError as ex:
            if ex.code == "content_filter":
@@ -97,10 +98,11 @@ class OpenAIBaseChatClient(OpenAIBase, BaseChatClient):
        chat_options: ChatOptions,
        **kwargs: Any,
    ) -> AsyncIterable[ChatResponseUpdate]:
+        client = await self.ensure_client()
        options_dict = self._prepare_options(messages, chat_options)
        options_dict["stream_options"] = {"include_usage": True}
        try:
-            async for chunk in await self.client.chat.completions.create(stream=True, **options_dict):
+            async for chunk in await client.chat.completions.create(stream=True, **options_dict):
                if len(chunk.choices) == 0 and chunk.usage is None:
                    continue
                yield self._create_chat_response_update(chunk)
@@ -89,23 +89,24 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
        chat_options: ChatOptions,
        **kwargs: Any,
    ) -> ChatResponse:
-        options_dict = self._prepare_options(messages, chat_options)
+        client = await self.ensure_client()
+        run_options = await self.prepare_options(messages, chat_options)
        try:
-            if not chat_options.response_format:
-                response = await self.client.responses.create(
+            response_format = run_options.pop("response_format", None)
+            if not response_format:
+                response = await client.responses.create(
                    stream=False,
-                    **options_dict,
+                    **run_options,
                )
-                chat_options.conversation_id = response.id if chat_options.store is True else None
+                chat_options.conversation_id = self.get_conversation_id(response, chat_options.store)
                return self._create_response_content(response, chat_options=chat_options)
            # create call does not support response_format, so we need to handle it via parse call
-            resp_format = chat_options.response_format
-            parsed_response: ParsedResponse[BaseModel] = await self.client.responses.parse(
-                text_format=resp_format,
+            parsed_response: ParsedResponse[BaseModel] = await client.responses.parse(
+                text_format=response_format,
                stream=False,
-                **options_dict,
+                **run_options,
            )
-            chat_options.conversation_id = parsed_response.id if chat_options.store is True else None
+            chat_options.conversation_id = self.get_conversation_id(parsed_response, chat_options.store)
            return self._create_response_content(parsed_response, chat_options=chat_options)
        except BadRequestError as ex:
            if ex.code == "content_filter":
@@ -130,13 +131,15 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
        chat_options: ChatOptions,
        **kwargs: Any,
    ) -> AsyncIterable[ChatResponseUpdate]:
-        options_dict = self._prepare_options(messages, chat_options)
+        client = await self.ensure_client()
+        run_options = await self.prepare_options(messages, chat_options)
        function_call_ids: dict[int, tuple[str, str]] = {}  # output_index: (call_id, name)
        try:
-            if not chat_options.response_format:
-                response = await self.client.responses.create(
+            response_format = run_options.pop("response_format", None)
+            if not response_format:
+                response = await client.responses.create(
                    stream=True,
-                    **options_dict,
+                    **run_options,
                )
                async for chunk in response:
                    update = self._create_streaming_response_content(
@@ -145,9 +148,9 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
                    yield update
                return
            # create call does not support response_format, so we need to handle it via stream call
-            async with self.client.responses.stream(
-                text_format=chat_options.response_format,
-                **options_dict,
+            async with client.responses.stream(
+                text_format=response_format,
+                **run_options,
            ) as response:
                async for chunk in response:
                    update = self._create_streaming_response_content(
@@ -170,6 +173,12 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
                inner_exception=ex,
            ) from ex

+    def get_conversation_id(
+        self, response: OpenAIResponse | ParsedResponse[BaseModel], store: bool | None
+    ) -> str | None:
+        """Get the conversation ID from the response if store is True."""
+        return response.id if store else None
+
    # region Prep methods

    def _tools_to_response_tools(
@@ -180,31 +189,7 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
            if isinstance(tool, ToolProtocol):
                match tool:
                    case HostedMCPTool():
-                        mcp: Mcp = {
-                            "type": "mcp",
-                            "server_label": tool.name.replace(" ", "_"),
-                            "server_url": str(tool.url),
-                            "server_description": tool.description,
-                            "headers": tool.headers,
-                        }
-                        if tool.allowed_tools:
-                            mcp["allowed_tools"] = list(tool.allowed_tools)
-                        if tool.approval_mode:
-                            match tool.approval_mode:
-                                case str():
-                                    mcp["require_approval"] = (
-                                        "always" if tool.approval_mode == "always_require" else "never"
-                                    )
-                                case _:
-                                    if always_require_approvals := tool.approval_mode.get("always_require_approval"):
-                                        mcp["require_approval"] = {
-                                            "always": {"tool_names": list(always_require_approvals)}
-                                        }
-                                    if never_require_approvals := tool.approval_mode.get("never_require_approval"):
-                                        mcp["require_approval"] = {
-                                            "never": {"tool_names": list(never_require_approvals)}
-                                        }
-                        response_tools.append(mcp)
+                        response_tools.append(self.get_mcp_tool(tool))
                    case HostedCodeInterpreterTool():
                        tool_args: CodeInterpreterContainerCodeInterpreterToolAuto = {"type": "auto"}
                        if tool.inputs:
@@ -293,17 +278,49 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
                            # Map the parameter name and remove the old one
                            mapped_tool[api_param] = mapped_tool.pop(user_param)

+                    # Validate partial_images parameter for streaming image generation
+                    # OpenAI API requires partial_images to be between 0-3 (inclusive) for image_generation tool
+                    # Reference: https://platform.openai.com/docs/api-reference/responses/create#responses_create-tools-image_generation_tool-partial_images
+                    if "partial_images" in mapped_tool:
+                        partial_images = mapped_tool["partial_images"]
+                        if not isinstance(partial_images, int) or partial_images < 0 or partial_images > 3:
+                            raise ValueError("partial_images must be an integer between 0 and 3 (inclusive).")
+
                    response_tools.append(mapped_tool)
                else:
                    response_tools.append(tool_dict)
        return response_tools

-    def _prepare_options(self, messages: MutableSequence[ChatMessage], chat_options: ChatOptions) -> dict[str, Any]:
+    def get_mcp_tool(self, tool: HostedMCPTool) -> Any:
+        """Get MCP tool from HostedMCPTool."""
+        mcp: Mcp = {
+            "type": "mcp",
+            "server_label": tool.name.replace(" ", "_"),
+            "server_url": str(tool.url),
+            "server_description": tool.description,
+            "headers": tool.headers,
+        }
+        if tool.allowed_tools:
+            mcp["allowed_tools"] = list(tool.allowed_tools)
+        if tool.approval_mode:
+            match tool.approval_mode:
+                case str():
+                    mcp["require_approval"] = "always" if tool.approval_mode == "always_require" else "never"
+                case _:
+                    if always_require_approvals := tool.approval_mode.get("always_require_approval"):
+                        mcp["require_approval"] = {"always": {"tool_names": list(always_require_approvals)}}
+                    if never_require_approvals := tool.approval_mode.get("never_require_approval"):
+                        mcp["require_approval"] = {"never": {"tool_names": list(never_require_approvals)}}
+
+        return mcp
+
+    async def prepare_options(
+        self, messages: MutableSequence[ChatMessage], chat_options: ChatOptions
+    ) -> dict[str, Any]:
        """Take ChatOptions and create the specific options for Responses API."""
-        options_dict: dict[str, Any] = chat_options.to_dict(
+        run_options: dict[str, Any] = chat_options.to_dict(
            exclude={
                "type",
-                "response_format",  # handled in inner get methods
                "presence_penalty",  # not supported
                "frequency_penalty",  # not supported
                "logit_bias",  # not supported
@@ -312,6 +329,10 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
                "instructions",  # already added as system message
            }
        )
+
+        if chat_options.response_format:
+            run_options["response_format"] = chat_options.response_format
+
        translations = {
            "model_id": "model",
            "allow_multiple_tool_calls": "parallel_tool_calls",
@@ -319,35 +340,37 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
            "max_tokens": "max_output_tokens",
        }
        for old_key, new_key in translations.items():
-            if old_key in options_dict and old_key != new_key:
-                options_dict[new_key] = options_dict.pop(old_key)
+            if old_key in run_options and old_key != new_key:
+                run_options[new_key] = run_options.pop(old_key)

        # tools
        if chat_options.tools is None:
-            options_dict.pop("parallel_tool_calls", None)
+            run_options.pop("parallel_tool_calls", None)
        else:
-            options_dict["tools"] = self._tools_to_response_tools(chat_options.tools)
+            run_options["tools"] = self._tools_to_response_tools(chat_options.tools)

        # model id
-        if not options_dict.get("model"):
-            options_dict["model"] = self.model_id
+        if not run_options.get("model"):
+            if not self.model_id:
+                raise ValueError("model_id must be a non-empty string")
+            run_options["model"] = self.model_id

        # messages
        request_input = self._prepare_chat_messages_for_request(messages)
        if not request_input:
            raise ServiceInvalidRequestError("Messages are required for chat completions")
-        options_dict["input"] = request_input
+        run_options["input"] = request_input

        # additional provider specific settings
-        if additional_properties := options_dict.pop("additional_properties", None):
+        if additional_properties := run_options.pop("additional_properties", None):
            for key, value in additional_properties.items():
                if value is not None:
-                    options_dict[key] = value
-        if "store" not in options_dict:
-            options_dict["store"] = False
-        if (tool_choice := options_dict.get("tool_choice")) and len(tool_choice.keys()) == 1:
-            options_dict["tool_choice"] = tool_choice["mode"]
-        return options_dict
+                    run_options[key] = value
+        if "store" not in run_options:
+            run_options["store"] = False
+        if (tool_choice := run_options.get("tool_choice")) and len(tool_choice.keys()) == 1:
+            run_options["tool_choice"] = tool_choice["mode"]
+        return run_options

    def _prepare_chat_messages_for_request(self, chat_messages: Sequence[ChatMessage]) -> list[dict[str, Any]]:
        """Prepare the chat messages for a request.
@@ -496,7 +519,6 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
                # call_id for the result needs to be the same as the call_id for the function call
                args: dict[str, Any] = {
                    "call_id": content.call_id,
-                    "id": call_id_to_id.get(content.call_id),
                    "type": "function_call_output",
                }
                if content.result:
@@ -695,29 +717,8 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
                        uri = item.result
                        media_type = None
                        if not uri.startswith("data:"):
-                            # Raw base64 string - convert to proper data URI format
-                            # Detect format from base64 data
-                            import base64
-
-                            try:
-                                # Decode a small portion to detect format
-                                decoded_data = base64.b64decode(uri[:100])  # First ~75 bytes should be enough
-                                if decoded_data.startswith(b"\x89PNG"):
-                                    format_type = "png"
-                                elif decoded_data.startswith(b"\xff\xd8\xff"):
-                                    format_type = "jpeg"
-                                elif decoded_data.startswith(b"RIFF") and b"WEBP" in decoded_data[:12]:
-                                    format_type = "webp"
-                                elif decoded_data.startswith(b"GIF87a") or decoded_data.startswith(b"GIF89a"):
-                                    format_type = "gif"
-                                else:
-                                    # Default to png if format cannot be detected
-                                    format_type = "png"
-                            except Exception:
-                                # Fallback to png if decoding fails
-                                format_type = "png"
-                            uri = f"data:image/{format_type};base64,{uri}"
-                            media_type = f"image/{format_type}"
+                            # Raw base64 string - convert to proper data URI format using helper
+                            uri, media_type = DataContent.create_data_uri_from_base64(uri)
                        else:
                            # Parse media type from existing data URI
                            try:
@@ -747,7 +748,7 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
            "raw_representation": response,
        }
        if chat_options.store:
-            args["conversation_id"] = response.id
+            args["conversation_id"] = self.get_conversation_id(response, chat_options.store)
        if response.usage and (usage_details := self._usage_details_from_openai(response.usage)):
            args["usage_details"] = usage_details
        if structured_response:
@@ -847,7 +848,7 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
                contents.append(TextReasoningContent(text=event.text, raw_representation=event))
                metadata.update(self._get_metadata_from_response(event))
            case "response.completed":
-                conversation_id = event.response.id if chat_options.store is True else None
+                conversation_id = self.get_conversation_id(event.response, chat_options.store)
                model = event.response.model
                if event.response.usage:
                    usage = self._usage_details_from_openai(event.response.usage)
@@ -933,6 +934,25 @@ class OpenAIBaseResponsesClient(OpenAIBase, BaseChatClient):
                            raw_representation=event,
                        )
                    )
+            case "response.image_generation_call.partial_image":
+                # Handle streaming partial image generation
+                image_base64 = event.partial_image_b64
+                partial_index = event.partial_image_index
+
+                # Use helper function to create data URI from base64
+                uri, media_type = DataContent.create_data_uri_from_base64(image_base64)
+
+                contents.append(
+                    DataContent(
+                        uri=uri,
+                        media_type=media_type,
+                        additional_properties={
+                            "partial_image_index": partial_index,
+                            "is_partial_image": True,
+                        },
+                        raw_representation=event,
+                    )
+                )
            case _:
                logger.debug("Unparsed event of type: %s: %s", event.type, event)

@@ -127,18 +127,18 @@ class OpenAIBase(SerializationMixin):

    INJECTABLE: ClassVar[set[str]] = {"client"}

-    def __init__(self, *, client: AsyncOpenAI, model_id: str, **kwargs: Any) -> None:
+    def __init__(self, *, model_id: str | None = None, client: AsyncOpenAI | None = None, **kwargs: Any) -> None:
        """Initialize OpenAIBase.

        Keyword Args:
            client: The AsyncOpenAI client instance.
-            model_id: The AI model ID to use (non-empty, whitespace stripped).
+            model_id: The AI model ID to use.
            **kwargs: Additional keyword arguments.
        """
-        if not model_id or not model_id.strip():
-            raise ValueError("model_id must be a non-empty string")
        self.client = client
-        self.model_id = model_id.strip()
+        self.model_id = None
+        if model_id:
+            self.model_id = model_id.strip()

        # Call super().__init__() to continue MRO chain (e.g., BaseChatClient)
        # Extract known kwargs that belong to other base classes
@@ -162,6 +162,21 @@ class OpenAIBase(SerializationMixin):
        for key, value in kwargs.items():
            setattr(self, key, value)

+    async def initialize_client(self) -> None:
+        """Initialize OpenAI client asynchronously.
+
+        Override in subclasses to initialize the OpenAI client asynchronously.
+        """
+        pass
+
+    async def ensure_client(self) -> AsyncOpenAI:
+        """Ensure OpenAI client is initialized."""
+        await self.initialize_client()
+        if self.client is None:
+            raise ServiceInitializationError("OpenAI client is not initialized")
+
+        return self.client
+
    def _get_api_key(
        self, api_key: str | SecretStr | Callable[[], str | Awaitable[str]] | None
    ) -> str | Callable[[], str | Awaitable[str]] | None:
@@ -4,7 +4,7 @@ description = "Microsoft Agent Framework for building AI Agents with Python. Thi
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -42,13 +42,14 @@ dependencies = [
 [project.optional-dependencies]
 all = [
    "agent-framework-a2a",
+    "agent-framework-ag-ui",
+    "agent-framework-anthropic",
    "agent-framework-azure-ai",
    "agent-framework-copilotstudio",
-    "agent-framework-mem0",
-    "agent-framework-redis",
    "agent-framework-devui",
+    "agent-framework-mem0",
    "agent-framework-purview",
-    "agent-framework-anthropic",
+    "agent-framework-redis",
 ]

 [tool.uv]
@@ -1,5 +1,6 @@
 # Copyright (c) Microsoft. All rights reserved.

+import base64
 from collections.abc import AsyncIterable
 from typing import Any

@@ -166,6 +167,57 @@ def test_data_content_empty():
        DataContent(uri="")


+def test_data_content_detect_image_format_from_base64():
+    """Test the detect_image_format_from_base64 static method."""
+    # Test each supported format
+    png_data = b"\x89PNG\r\n\x1a\n" + b"fake_data"
+    assert DataContent.detect_image_format_from_base64(base64.b64encode(png_data).decode()) == "png"
+
+    jpeg_data = b"\xff\xd8\xff\xe0" + b"fake_data"
+    assert DataContent.detect_image_format_from_base64(base64.b64encode(jpeg_data).decode()) == "jpeg"
+
+    webp_data = b"RIFF" + b"1234" + b"WEBP" + b"fake_data"
+    assert DataContent.detect_image_format_from_base64(base64.b64encode(webp_data).decode()) == "webp"
+
+    gif_data = b"GIF89a" + b"fake_data"
+    assert DataContent.detect_image_format_from_base64(base64.b64encode(gif_data).decode()) == "gif"
+
+    # Test fallback behavior
+    unknown_data = b"UNKNOWN_FORMAT"
+    assert DataContent.detect_image_format_from_base64(base64.b64encode(unknown_data).decode()) == "png"
+
+    # Test error handling
+    assert DataContent.detect_image_format_from_base64("invalid_base64!") == "png"
+    assert DataContent.detect_image_format_from_base64("") == "png"
+
+
+def test_data_content_create_data_uri_from_base64():
+    """Test the create_data_uri_from_base64 class method."""
+    # Test with PNG data
+    png_data = b"\x89PNG\r\n\x1a\n" + b"fake_data"
+    png_base64 = base64.b64encode(png_data).decode()
+    uri, media_type = DataContent.create_data_uri_from_base64(png_base64)
+
+    assert uri == f"data:image/png;base64,{png_base64}"
+    assert media_type == "image/png"
+
+    # Test with different format
+    jpeg_data = b"\xff\xd8\xff\xe0" + b"fake_data"
+    jpeg_base64 = base64.b64encode(jpeg_data).decode()
+    uri, media_type = DataContent.create_data_uri_from_base64(jpeg_base64)
+
+    assert uri == f"data:image/jpeg;base64,{jpeg_base64}"
+    assert media_type == "image/jpeg"
+
+    # Test fallback for unknown format
+    unknown_data = b"UNKNOWN_FORMAT"
+    unknown_base64 = base64.b64encode(unknown_data).decode()
+    uri, media_type = DataContent.create_data_uri_from_base64(unknown_base64)
+
+    assert uri == f"data:image/png;base64,{unknown_base64}"
+    assert media_type == "image/png"
+
+
 # region UriContent


@@ -111,6 +111,10 @@ async def test_agent_executor_checkpoint_stores_and_restores_state() -> None:
    chat_store_state = thread_state["chat_message_store_state"]  # type: ignore[index]
    assert "messages" in chat_store_state, "Message store state should include messages"

+    # Verify checkpoint contains pending requests from agents and responses to be sent
+    assert "pending_agent_requests" in executor_state
+    assert "pending_responses_to_agent" in executor_state
+
    # Create a new agent and executor for restoration
    # This simulates starting from a fresh state and restoring from checkpoint
    restored_agent = _CountingAgent(id="test_agent", name="TestAgent")
@@ -5,19 +5,32 @@
 from collections.abc import AsyncIterable
 from typing import Any

+from typing_extensions import Never
+
 from agent_framework import (
    AgentExecutor,
+    AgentExecutorResponse,
    AgentRunResponse,
    AgentRunResponseUpdate,
    AgentRunUpdateEvent,
    AgentThread,
    BaseAgent,
+    ChatAgent,
    ChatMessage,
+    ChatResponse,
+    ChatResponseUpdate,
+    FunctionApprovalRequestContent,
    FunctionCallContent,
    FunctionResultContent,
+    RequestInfoEvent,
    Role,
    TextContent,
    WorkflowBuilder,
+    WorkflowContext,
+    WorkflowOutputEvent,
+    ai_function,
+    executor,
+    use_function_invocation,
 )


@@ -120,3 +133,235 @@ async def test_agent_executor_emits_tool_calls_in_streaming_mode() -> None:
    assert events[3].data is not None
    assert isinstance(events[3].data.contents[0], TextContent)
    assert "sunny" in events[3].data.contents[0].text
+
+
+@ai_function(approval_mode="always_require")
+def mock_tool_requiring_approval(query: str) -> str:
+    """Mock tool that requires approval before execution."""
+    return f"Executed tool with query: {query}"
+
+
+@use_function_invocation
+class MockChatClient:
+    """Simple implementation of a chat client."""
+
+    def __init__(self, parallel_request: bool = False) -> None:
+        self.additional_properties: dict[str, Any] = {}
+        self._iteration: int = 0
+        self._parallel_request: bool = parallel_request
+
+    async def get_response(
+        self,
+        messages: str | ChatMessage | list[str] | list[ChatMessage],
+        **kwargs: Any,
+    ) -> ChatResponse:
+        if self._iteration == 0:
+            if self._parallel_request:
+                response = ChatResponse(
+                    messages=ChatMessage(
+                        role="assistant",
+                        contents=[
+                            FunctionCallContent(
+                                call_id="1", name="mock_tool_requiring_approval", arguments='{"query": "test"}'
+                            ),
+                            FunctionCallContent(
+                                call_id="2", name="mock_tool_requiring_approval", arguments='{"query": "test"}'
+                            ),
+                        ],
+                    )
+                )
+            else:
+                response = ChatResponse(
+                    messages=ChatMessage(
+                        role="assistant",
+                        contents=[
+                            FunctionCallContent(
+                                call_id="1", name="mock_tool_requiring_approval", arguments='{"query": "test"}'
+                            )
+                        ],
+                    )
+                )
+        else:
+            response = ChatResponse(messages=ChatMessage(role="assistant", text="Tool executed successfully."))
+
+        self._iteration += 1
+        return response
+
+    async def get_streaming_response(
+        self,
+        messages: str | ChatMessage | list[str] | list[ChatMessage],
+        **kwargs: Any,
+    ) -> AsyncIterable[ChatResponseUpdate]:
+        if self._iteration == 0:
+            if self._parallel_request:
+                yield ChatResponseUpdate(
+                    contents=[
+                        FunctionCallContent(
+                            call_id="1", name="mock_tool_requiring_approval", arguments='{"query": "test"}'
+                        ),
+                        FunctionCallContent(
+                            call_id="2", name="mock_tool_requiring_approval", arguments='{"query": "test"}'
+                        ),
+                    ],
+                    role="assistant",
+                )
+            else:
+                yield ChatResponseUpdate(
+                    contents=[
+                        FunctionCallContent(
+                            call_id="1", name="mock_tool_requiring_approval", arguments='{"query": "test"}'
+                        )
+                    ],
+                    role="assistant",
+                )
+        else:
+            yield ChatResponseUpdate(text=TextContent(text="Tool executed "), role="assistant")
+            yield ChatResponseUpdate(contents=[TextContent(text="successfully.")], role="assistant")
+
+        self._iteration += 1
+
+
+@executor(id="test_executor")
+async def test_executor(agent_executor_response: AgentExecutorResponse, ctx: WorkflowContext[Never, str]) -> None:
+    await ctx.yield_output(agent_executor_response.agent_run_response.text)
+
+
+async def test_agent_executor_tool_call_with_approval() -> None:
+    """Test that AgentExecutor handles tool calls requiring approval."""
+    # Arrange
+    agent = ChatAgent(
+        chat_client=MockChatClient(),
+        name="ApprovalAgent",
+        tools=[mock_tool_requiring_approval],
+    )
+
+    workflow = WorkflowBuilder().set_start_executor(agent).add_edge(agent, test_executor).build()
+
+    # Act
+    events = await workflow.run("Invoke tool requiring approval")
+
+    # Assert
+    assert len(events.get_request_info_events()) == 1
+    approval_request = events.get_request_info_events()[0]
+    assert isinstance(approval_request.data, FunctionApprovalRequestContent)
+    assert approval_request.data.function_call.name == "mock_tool_requiring_approval"
+    assert approval_request.data.function_call.arguments == '{"query": "test"}'
+
+    # Act
+    events = await workflow.send_responses({approval_request.request_id: approval_request.data.create_response(True)})
+
+    # Assert
+    final_response = events.get_outputs()
+    assert len(final_response) == 1
+    assert final_response[0] == "Tool executed successfully."
+
+
+async def test_agent_executor_tool_call_with_approval_streaming() -> None:
+    """Test that AgentExecutor handles tool calls requiring approval in streaming mode."""
+    # Arrange
+    agent = ChatAgent(
+        chat_client=MockChatClient(),
+        name="ApprovalAgent",
+        tools=[mock_tool_requiring_approval],
+    )
+
+    workflow = WorkflowBuilder().set_start_executor(agent).add_edge(agent, test_executor).build()
+
+    # Act
+    request_info_events: list[RequestInfoEvent] = []
+    async for event in workflow.run_stream("Invoke tool requiring approval"):
+        if isinstance(event, RequestInfoEvent):
+            request_info_events.append(event)
+
+    # Assert
+    assert len(request_info_events) == 1
+    approval_request = request_info_events[0]
+    assert isinstance(approval_request.data, FunctionApprovalRequestContent)
+    assert approval_request.data.function_call.name == "mock_tool_requiring_approval"
+    assert approval_request.data.function_call.arguments == '{"query": "test"}'
+
+    # Act
+    output: str | None = None
+    async for event in workflow.send_responses_streaming({
+        approval_request.request_id: approval_request.data.create_response(True)
+    }):
+        if isinstance(event, WorkflowOutputEvent):
+            output = event.data
+
+    # Assert
+    assert output is not None
+    assert output == "Tool executed successfully."
+
+
+async def test_agent_executor_parallel_tool_call_with_approval() -> None:
+    """Test that AgentExecutor handles parallel tool calls requiring approval."""
+    # Arrange
+    agent = ChatAgent(
+        chat_client=MockChatClient(parallel_request=True),
+        name="ApprovalAgent",
+        tools=[mock_tool_requiring_approval],
+    )
+
+    workflow = WorkflowBuilder().set_start_executor(agent).add_edge(agent, test_executor).build()
+
+    # Act
+    events = await workflow.run("Invoke tool requiring approval")
+
+    # Assert
+    assert len(events.get_request_info_events()) == 2
+    for approval_request in events.get_request_info_events():
+        assert isinstance(approval_request.data, FunctionApprovalRequestContent)
+        assert approval_request.data.function_call.name == "mock_tool_requiring_approval"
+        assert approval_request.data.function_call.arguments == '{"query": "test"}'
+
+    # Act
+    responses = {
+        approval_request.request_id: approval_request.data.create_response(True)  # type: ignore
+        for approval_request in events.get_request_info_events()
+    }
+    events = await workflow.send_responses(responses)
+
+    # Assert
+    final_response = events.get_outputs()
+    assert len(final_response) == 1
+    assert final_response[0] == "Tool executed successfully."
+
+
+async def test_agent_executor_parallel_tool_call_with_approval_streaming() -> None:
+    """Test that AgentExecutor handles parallel tool calls requiring approval in streaming mode."""
+    # Arrange
+    agent = ChatAgent(
+        chat_client=MockChatClient(parallel_request=True),
+        name="ApprovalAgent",
+        tools=[mock_tool_requiring_approval],
+    )
+
+    workflow = WorkflowBuilder().set_start_executor(agent).add_edge(agent, test_executor).build()
+
+    # Act
+    request_info_events: list[RequestInfoEvent] = []
+    async for event in workflow.run_stream("Invoke tool requiring approval"):
+        if isinstance(event, RequestInfoEvent):
+            request_info_events.append(event)
+
+    # Assert
+    assert len(request_info_events) == 2
+    for approval_request in request_info_events:
+        assert isinstance(approval_request.data, FunctionApprovalRequestContent)
+        assert approval_request.data.function_call.name == "mock_tool_requiring_approval"
+        assert approval_request.data.function_call.arguments == '{"query": "test"}'
+
+    # Act
+    responses = {
+        approval_request.request_id: approval_request.data.create_response(True)  # type: ignore
+        for approval_request in request_info_events
+    }
+
+    output: str | None = None
+    async for event in workflow.send_responses_streaming(responses):
+        if isinstance(event, WorkflowOutputEvent):
+            output = event.data
+
+    # Assert
+    assert output is not None
+    assert output == "Tool executed successfully."
@@ -4,7 +4,7 @@ description = "Debug UI for Microsoft Agent Framework with OpenAI-compatible API
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://github.com/microsoft/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -4,7 +4,7 @@ description = "Experimental modules for Microsoft Agent Framework"
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -56,7 +56,7 @@ math = [

 [dependency-groups]
 dev = [
-    "uv>=0.8.2,<0.9.0",
+    "uv",
    "pre-commit >= 3.7",
    "ruff>=0.11.8",
    "pytest>=8.4.1",
@@ -4,7 +4,7 @@ description = "Mem0 integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -4,7 +4,7 @@ description = "Microsoft Purview (Graph dataSecurityAndGovernance) integration f
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://github.com/microsoft/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -4,7 +4,7 @@ description = "Redis integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -4,7 +4,7 @@ description = "Microsoft Agent Framework for building AI Agents with Python. Thi
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b251108"
+version = "1.0.0b251111"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -39,7 +39,7 @@ dependencies = [

 [dependency-groups]
 dev = [
-    "uv>=0.8.2,<0.10.0",
+    "uv>=0.9,<1.0.0",
    "flit>=3.12.0",
    "pre-commit >= 3.7",
    "ruff>=0.11.8",
@@ -21,20 +21,20 @@ This directory contains samples demonstrating the capabilities of Microsoft Agen

 | File | Description |
 |------|-------------|
-| [`getting_started/agents/azure_ai/azure_ai_basic.py`](./getting_started/agents/azure_ai/azure_ai_basic.py) | Azure AI Agent Basic Example |
-| [`getting_started/agents/azure_ai/azure_ai_with_azure_ai_search.py`](./getting_started/agents/azure_ai/azure_ai_with_azure_ai_search.py) | Azure AI Agent with Azure AI Search Example |
-| [`getting_started/agents/azure_ai/azure_ai_with_bing_grounding.py`](./getting_started/agents/azure_ai/azure_ai_with_bing_grounding.py) | Azure AI agent with Bing Grounding search for real-time web information |
-| [`getting_started/agents/azure_ai/azure_ai_with_code_interpreter.py`](./getting_started/agents/azure_ai/azure_ai_with_code_interpreter.py) | Azure AI Agent with Code Interpreter Example |
-| [`getting_started/agents/azure_ai/azure_ai_with_existing_agent.py`](./getting_started/agents/azure_ai/azure_ai_with_existing_agent.py) | Azure AI Agent with Existing Agent Example |
-| [`getting_started/agents/azure_ai/azure_ai_with_existing_thread.py`](./getting_started/agents/azure_ai/azure_ai_with_existing_thread.py) | Azure AI Agent with Existing Thread Example |
-| [`getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py`](./getting_started/agents/azure_ai/azure_ai_with_explicit_settings.py) | Azure AI Agent with Explicit Settings Example |
-| [`getting_started/agents/azure_ai/azure_ai_with_file_search.py`](./getting_started/agents/azure_ai/azure_ai_with_file_search.py) | Azure AI agent with File Search capabilities |
-| [`getting_started/agents/azure_ai/azure_ai_with_function_tools.py`](./getting_started/agents/azure_ai/azure_ai_with_function_tools.py) | Azure AI Agent with Function Tools Example |
-| [`getting_started/agents/azure_ai/azure_ai_with_hosted_mcp.py`](./getting_started/agents/azure_ai/azure_ai_with_hosted_mcp.py) | Azure AI Agent with Hosted MCP Example |
-| [`getting_started/agents/azure_ai/azure_ai_with_local_mcp.py`](./getting_started/agents/azure_ai/azure_ai_with_local_mcp.py) | Azure AI Agent with Local MCP Example |
-| [`getting_started/agents/azure_ai/azure_ai_with_multiple_tools.py`](./getting_started/agents/azure_ai/azure_ai_with_multiple_tools.py) | Azure AI Agent with Multiple Tools Example |
-| [`getting_started/agents/azure_ai/azure_ai_with_openapi_tools.py`](./getting_started/agents/azure_ai/azure_ai_with_openapi_tools.py) | Azure AI agent with OpenAPI tools |
-| [`getting_started/agents/azure_ai/azure_ai_with_thread.py`](./getting_started/agents/azure_ai/azure_ai_with_thread.py) | Azure AI Agent with Thread Management Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_basic.py`](./getting_started/agents/azure_ai/azure_ai_basic.py) | Azure AI Agent Basic Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_azure_ai_search.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_azure_ai_search.py) | Azure AI Agent with Azure AI Search Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_bing_grounding.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_bing_grounding.py) | Azure AI agent with Bing Grounding search for real-time web information |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_code_interpreter.py) | Azure AI Agent with Code Interpreter Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_existing_agent.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_existing_agent.py) | Azure AI Agent with Existing Agent Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_existing_thread.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_existing_thread.py) | Azure AI Agent with Existing Thread Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_explicit_settings.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_explicit_settings.py) | Azure AI Agent with Explicit Settings Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_file_search.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_file_search.py) | Azure AI agent with File Search capabilities |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_function_tools.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_function_tools.py) | Azure AI Agent with Function Tools Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_hosted_mcp.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_hosted_mcp.py) | Azure AI Agent with Hosted MCP Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_local_mcp.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_local_mcp.py) | Azure AI Agent with Local MCP Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_multiple_tools.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_multiple_tools.py) | Azure AI Agent with Multiple Tools Example |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_openapi_tools.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_openapi_tools.py) | Azure AI agent with OpenAPI tools |
+| [`getting_started/agents/azure_ai_agent/azure_ai_with_thread.py`](./getting_started/agents/azure_ai_agent/azure_ai_with_thread.py) | Azure AI Agent with Thread Management Example |

 ### Azure OpenAI

@@ -281,6 +281,7 @@ This directory contains samples demonstrating the capabilities of Microsoft Agen
 | File | Description |
 |------|-------------|
 | [`getting_started/workflows/human-in-the-loop/guessing_game_with_human_input.py`](./getting_started/workflows/human-in-the-loop/guessing_game_with_human_input.py) | Sample: Human in the loop guessing game |
+| [`getting_started/workflows/human-in-the-loop/agents_with_approval_requests.py`](./getting_started/workflows/human-in-the-loop/agents_with_approval_requests.py) | Sample: Agents with Approval Requests in Workflows |

 ### Observability

@@ -17,7 +17,7 @@
                "@types/react-dom": "^19.2.0",
                "@vitejs/plugin-react-swc": "^3.5.0",
                "typescript": "^5.4.0",
-                "vite": "^7.1.9"
+                "vite": "^7.1.12"
            },
            "engines": {
                "node": ">=18.18",
@@ -1328,9 +1328,9 @@
            }
        },
        "node_modules/vite": {
-            "version": "7.1.9",
-            "resolved": "https://registry.npmjs.org/vite/-/vite-7.1.9.tgz",
-            "integrity": "sha512-4nVGliEpxmhCL8DslSAUdxlB6+SMrhB0a1v5ijlh1xB1nEPuy1mxaHxysVucLHuWryAxLWg6a5ei+U4TLn/rFg==",
+            "version": "7.1.12",
+            "resolved": "https://registry.npmjs.org/vite/-/vite-7.1.12.tgz",
+            "integrity": "sha512-ZWyE8YXEXqJrrSLvYgrRP7p62OziLW7xI5HYGWFzOvupfAlrLvURSzv/FyGyy0eidogEM3ujU+kUG1zuHgb6Ug==",
            "dev": true,
            "license": "MIT",
            "dependencies": {
--- a/Show More
+++ b/Show More