Python: Bump ag-ui package to 1.0.0b251105 for a release. Update changelog. (#1922)

* Bump ag-ui package to 1.0.0b251105 for a release. Update changelog.

* Fix authors and license-files

.gitignore

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

dotnet/agent-framework-dotnet.slnx

@@ -143,6 +143,7 @@
     <Project Path="samples/GettingStarted/Workflows/_Foundational/05_MultiModelService/05_MultiModelService.csproj" />
     <Project Path="samples/GettingStarted/Workflows/_Foundational/06_SubWorkflows/06_SubWorkflows.csproj" />
     <Project Path="samples/GettingStarted/Workflows/_Foundational/07_MixedWorkflowAgentsAndExecutors/07_MixedWorkflowAgentsAndExecutors.csproj" />
+    <Project Path="samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/08_WriterCriticWorkflow.csproj" />
   </Folder>
   <Folder Name="/Samples/Catalog/">
     <Project Path="samples/Catalog/AgentWithTextSearchRag/AgentWithTextSearchRag.csproj" />

dotnet/nuget/nuget-package.props

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

dotnet/samples/GettingStarted/Workflows/README.md

@@ -19,6 +19,7 @@ Please begin with the [Foundational](./_Foundational) samples in order. These th
 | [Multi-Service Workflows](./_Foundational/05_MultiModelService) | Shows using multiple AI services in the same workflow |
 | [Sub-Workflows](./_Foundational/06_SubWorkflows) | Demonstrates composing workflows hierarchically by embedding workflows as executors |
 | [Mixed Workflow with Agents and Executors](./_Foundational/07_MixedWorkflowAgentsAndExecutors) | Shows how to mix agents and executors with adapter pattern for type conversion and protocol handling |
+| [Writer-Critic Workflow](./_Foundational/08_WriterCriticWorkflow) | Demonstrates iterative refinement with quality gates, max iteration safety, multiple message handlers, and conditional routing for feedback loops |
 
 Once completed, please proceed to other samples listed below.
 

dotnet/samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/08_WriterCriticWorkflow.csproj

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

dotnet/samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/Program.cs

@@ -0,0 +1,409 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Diagnostics.CodeAnalysis;
+using System.Text;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WriterCriticWorkflow;
+
+/// <summary>
+/// This sample demonstrates an iterative refinement workflow between Writer and Critic agents.
+///
+/// The workflow implements a content creation and review loop that:
+/// 1. Writer creates initial content based on the user's request
+/// 2. Critic reviews the content and provides feedback using structured output
+/// 3. If approved: Summary executor presents the final content
+/// 4. If rejected: Writer revises based on feedback (loops back)
+/// 5. Continues until approval or max iterations (3) is reached
+///
+/// This pattern is useful when you need:
+/// - Iterative content improvement through feedback loops
+/// - Quality gates with reviewer approval
+/// - Maximum iteration limits to prevent infinite loops
+/// - Conditional workflow routing based on agent decisions
+/// - Structured output for reliable decision-making
+///
+/// Key Learning: Workflows can implement loops with conditional edges, shared state,
+/// and structured output for robust agent decision-making.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Previous foundational samples should be completed first.
+/// - An Azure OpenAI chat completion deployment must be configured.
+/// </remarks>
+public static class Program
+{
+    public const int MaxIterations = 3;
+
+    private static async Task Main()
+    {
+        Console.WriteLine("\n=== Writer-Critic Iteration Workflow ===\n");
+        Console.WriteLine($"Writer and Critic will iterate up to {MaxIterations} times until approval.\n");
+
+        // Set up the Azure OpenAI client
+        string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+        string deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+        IChatClient chatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential()).GetChatClient(deploymentName).AsIChatClient();
+
+        // Create executors for content creation and review
+        WriterExecutor writer = new(chatClient);
+        CriticExecutor critic = new(chatClient);
+        SummaryExecutor summary = new(chatClient);
+
+        // Build the workflow with conditional routing based on critic's decision
+        WorkflowBuilder workflowBuilder = new WorkflowBuilder(writer)
+            .AddEdge(writer, critic)
+            .AddSwitch(critic, sw => sw
+                .AddCase<CriticDecision>(cd => cd?.Approved == true, summary)
+                .AddCase<CriticDecision>(cd => cd?.Approved == false, writer))
+            .WithOutputFrom(summary);
+
+        // Execute the workflow with a sample task
+        // The workflow loops back to Writer if content is rejected,
+        // or proceeds to Summary if approved. State tracking ensures we don't loop forever.
+        Console.WriteLine(new string('=', 80));
+        Console.WriteLine("TASK: Write a short blog post about AI ethics (200 words)");
+        Console.WriteLine(new string('=', 80) + "\n");
+
+        const string InitialTask = "Write a 200-word blog post about AI ethics. Make it thoughtful and engaging.";
+
+        Workflow workflow = workflowBuilder.Build();
+        await ExecuteWorkflowAsync(workflow, InitialTask);
+
+        Console.WriteLine("\n✅ Sample Complete: Writer-Critic iteration demonstrates conditional workflow loops\n");
+        Console.WriteLine("Key Concepts Demonstrated:");
+        Console.WriteLine("  ✓ Iterative refinement loop with conditional routing");
+        Console.WriteLine("  ✓ Shared workflow state for iteration tracking");
+        Console.WriteLine($"  ✓ Max iteration cap ({MaxIterations}) for safety");
+        Console.WriteLine("  ✓ Multiple message handlers in a single executor");
+        Console.WriteLine("  ✓ Streaming support with structured output\n");
+    }
+
+    private static async Task ExecuteWorkflowAsync(Workflow workflow, string input)
+    {
+        // Execute in streaming mode to see real-time progress
+        await using StreamingRun run = await InProcessExecution.StreamAsync<string>(workflow, input);
+
+        // Watch the workflow events
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            switch (evt)
+            {
+                case AgentRunUpdateEvent agentUpdate:
+                    // Stream agent output in real-time
+                    if (!string.IsNullOrEmpty(agentUpdate.Update.Text))
+                    {
+                        Console.Write(agentUpdate.Update.Text);
+                    }
+                    break;
+
+                case WorkflowOutputEvent output:
+                    Console.WriteLine("\n\n" + new string('=', 80));
+                    Console.ForegroundColor = ConsoleColor.Green;
+                    Console.WriteLine("✅ FINAL APPROVED CONTENT");
+                    Console.ResetColor();
+                    Console.WriteLine(new string('=', 80));
+                    Console.WriteLine();
+                    Console.WriteLine(output.Data);
+                    Console.WriteLine();
+                    Console.WriteLine(new string('=', 80));
+                    break;
+            }
+        }
+    }
+}
+
+// ====================================
+// Shared State for Iteration Tracking
+// ====================================
+
+/// <summary>
+/// Tracks the current iteration and conversation history across workflow executions.
+/// </summary>
+internal sealed class FlowState
+{
+    public int Iteration { get; set; } = 1;
+    public List<ChatMessage> History { get; } = [];
+}
+
+/// <summary>
+/// Constants for accessing the shared flow state in workflow context.
+/// </summary>
+internal static class FlowStateShared
+{
+    public const string Scope = "FlowStateScope";
+    public const string Key = "singleton";
+}
+
+/// <summary>
+/// Helper methods for reading and writing shared flow state.
+/// </summary>
+internal static class FlowStateHelpers
+{
+    public static async Task<FlowState> ReadFlowStateAsync(IWorkflowContext context)
+    {
+        FlowState? state = await context.ReadStateAsync<FlowState>(FlowStateShared.Key, scopeName: FlowStateShared.Scope);
+        return state ?? new FlowState();
+    }
+
+    public static ValueTask SaveFlowStateAsync(IWorkflowContext context, FlowState state)
+        => context.QueueStateUpdateAsync(FlowStateShared.Key, state, scopeName: FlowStateShared.Scope);
+}
+
+// ====================================
+// Data Transfer Objects
+// ====================================
+
+/// <summary>
+/// Structured output schema for the Critic's decision.
+/// Uses JsonPropertyName and Description attributes for OpenAI's JSON schema.
+/// </summary>
+[Description("Critic's review decision including approval status and feedback")]
+[SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated via JSON deserialization")]
+internal sealed class CriticDecision
+{
+    [JsonPropertyName("approved")]
+    [Description("Whether the content is approved (true) or needs revision (false)")]
+    public bool Approved { get; set; }
+
+    [JsonPropertyName("feedback")]
+    [Description("Specific feedback for improvements if not approved, empty if approved")]
+    public string Feedback { get; set; } = "";
+
+    // Non-JSON properties for workflow use
+    [JsonIgnore]
+    public string Content { get; set; } = "";
+
+    [JsonIgnore]
+    public int Iteration { get; set; }
+}
+
+// ====================================
+// Custom Executors
+// ====================================
+
+/// <summary>
+/// Executor that creates or revises content based on user requests or critic feedback.
+/// This executor demonstrates multiple message handlers for different input types.
+/// </summary>
+internal sealed class WriterExecutor : Executor
+{
+    private readonly AIAgent _agent;
+
+    public WriterExecutor(IChatClient chatClient) : base("Writer")
+    {
+        this._agent = new ChatClientAgent(
+            chatClient,
+            name: "Writer",
+            instructions: """
+                You are a skilled writer. Create clear, engaging content.
+                If you receive feedback, carefully revise the content to address all concerns.
+                Maintain the same topic and length requirements.
+                """
+        );
+    }
+
+    protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder) =>
+        routeBuilder
+            .AddHandler<string, ChatMessage>(this.HandleInitialRequestAsync)
+            .AddHandler<CriticDecision, ChatMessage>(this.HandleRevisionRequestAsync);
+
+    /// <summary>
+    /// Handles the initial writing request from the user.
+    /// </summary>
+    private async ValueTask<ChatMessage> HandleInitialRequestAsync(
+        string message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        return await this.HandleAsyncCoreAsync(new ChatMessage(ChatRole.User, message), context, cancellationToken);
+    }
+
+    /// <summary>
+    /// Handles revision requests from the critic with feedback.
+    /// </summary>
+    private async ValueTask<ChatMessage> HandleRevisionRequestAsync(
+        CriticDecision decision,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        string prompt = "Revise the following content based on this feedback:\n\n" +
+                       $"Feedback: {decision.Feedback}\n\n" +
+                       $"Original Content:\n{decision.Content}";
+
+        return await this.HandleAsyncCoreAsync(new ChatMessage(ChatRole.User, prompt), context, cancellationToken);
+    }
+
+    /// <summary>
+    /// Core implementation for generating content (initial or revised).
+    /// </summary>
+    private async Task<ChatMessage> HandleAsyncCoreAsync(
+        ChatMessage message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken)
+    {
+        FlowState state = await FlowStateHelpers.ReadFlowStateAsync(context);
+
+        Console.WriteLine($"\n=== Writer (Iteration {state.Iteration}) ===\n");
+
+        StringBuilder sb = new();
+        await foreach (AgentRunResponseUpdate update in this._agent.RunStreamingAsync(message, cancellationToken: cancellationToken))
+        {
+            if (!string.IsNullOrEmpty(update.Text))
+            {
+                sb.Append(update.Text);
+                Console.Write(update.Text);
+            }
+        }
+        Console.WriteLine("\n");
+
+        string text = sb.ToString();
+        state.History.Add(new ChatMessage(ChatRole.Assistant, text));
+        await FlowStateHelpers.SaveFlowStateAsync(context, state);
+
+        return new ChatMessage(ChatRole.User, text);
+    }
+}
+
+/// <summary>
+/// Executor that reviews content and decides whether to approve or request revisions.
+/// Uses structured output with streaming for reliable decision-making.
+/// </summary>
+internal sealed class CriticExecutor : Executor<ChatMessage, CriticDecision>
+{
+    private readonly AIAgent _agent;
+
+    public CriticExecutor(IChatClient chatClient) : base("Critic")
+    {
+        this._agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
+        {
+            Name = "Critic",
+            Instructions = """
+                You are a constructive critic. Review the content and provide specific feedback.
+                Always try to provide actionable suggestions for improvement and strive to identify improvement points.
+                Only approve if the content is high quality, clear, and meets the original requirements and you see no improvement points.
+                
+                Provide your decision as structured output with:
+                - approved: true if content is good, false if revisions needed
+                - feedback: specific improvements needed (empty if approved)
+                
+                Be concise but specific in your feedback.
+                """,
+            ChatOptions = new()
+            {
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<CriticDecision>()
+            }
+        });
+    }
+
+    public override async ValueTask<CriticDecision> HandleAsync(
+        ChatMessage message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        FlowState state = await FlowStateHelpers.ReadFlowStateAsync(context);
+
+        Console.WriteLine($"=== Critic (Iteration {state.Iteration}) ===\n");
+
+        // Use RunStreamingAsync to get streaming updates, then deserialize at the end
+        IAsyncEnumerable<AgentRunResponseUpdate> updates = this._agent.RunStreamingAsync(message, cancellationToken: cancellationToken);
+
+        // Stream the output in real-time (for any rationale/explanation)
+        await foreach (AgentRunResponseUpdate update in updates)
+        {
+            if (!string.IsNullOrEmpty(update.Text))
+            {
+                Console.Write(update.Text);
+            }
+        }
+        Console.WriteLine("\n");
+
+        // Convert the stream to a response and deserialize the structured output
+        AgentRunResponse response = await updates.ToAgentRunResponseAsync(cancellationToken);
+        CriticDecision decision = response.Deserialize<CriticDecision>(JsonSerializerOptions.Web);
+
+        Console.WriteLine($"Decision: {(decision.Approved ? "✅ APPROVED" : "❌ NEEDS REVISION")}");
+        if (!string.IsNullOrEmpty(decision.Feedback))
+        {
+            Console.WriteLine($"Feedback: {decision.Feedback}");
+        }
+        Console.WriteLine();
+
+        // Safety: approve if max iterations reached
+        if (!decision.Approved && state.Iteration >= Program.MaxIterations)
+        {
+            Console.ForegroundColor = ConsoleColor.Yellow;
+            Console.WriteLine($"⚠️ Max iterations ({Program.MaxIterations}) reached - auto-approving");
+            Console.ResetColor();
+            decision.Approved = true;
+            decision.Feedback = "";
+        }
+
+        // Increment iteration ONLY if rejecting (will loop back to Writer)
+        if (!decision.Approved)
+        {
+            state.Iteration++;
+        }
+
+        // Store the decision in history
+        state.History.Add(new ChatMessage(ChatRole.Assistant,
+            $"[Decision: {(decision.Approved ? "Approved" : "Needs Revision")}] {decision.Feedback}"));
+        await FlowStateHelpers.SaveFlowStateAsync(context, state);
+
+        // Populate workflow-specific fields
+        decision.Content = message.Text ?? "";
+        decision.Iteration = state.Iteration;
+
+        return decision;
+    }
+}
+
+/// <summary>
+/// Executor that presents the final approved content to the user.
+/// </summary>
+internal sealed class SummaryExecutor : Executor<CriticDecision, ChatMessage>
+{
+    private readonly AIAgent _agent;
+
+    public SummaryExecutor(IChatClient chatClient) : base("Summary")
+    {
+        this._agent = new ChatClientAgent(
+            chatClient,
+            name: "Summary",
+            instructions: """
+                You present the final approved content to the user.
+                Simply output the polished content - no additional commentary needed.
+                """
+        );
+    }
+
+    public override async ValueTask<ChatMessage> HandleAsync(
+        CriticDecision message,
+        IWorkflowContext context,
+        CancellationToken cancellationToken = default)
+    {
+        Console.WriteLine("=== Summary ===\n");
+
+        string prompt = $"Present this approved content:\n\n{message.Content}";
+
+        StringBuilder sb = new();
+        await foreach (AgentRunResponseUpdate update in this._agent.RunStreamingAsync(new ChatMessage(ChatRole.User, prompt), cancellationToken: cancellationToken))
+        {
+            if (!string.IsNullOrEmpty(update.Text))
+            {
+                sb.Append(update.Text);
+            }
+        }
+
+        ChatMessage result = new(ChatRole.Assistant, sb.ToString());
+        await context.YieldOutputAsync(result, cancellationToken);
+        return result;
+    }
+}

dotnet/src/Microsoft.Agents.AI.Workflows/Execution/StreamingRunEventStream.cs

@@ -2,10 +2,12 @@
 
 using System;
 using System.Collections.Generic;
+using System.Diagnostics;
 using System.Runtime.CompilerServices;
 using System.Threading;
 using System.Threading.Channels;
 using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.Observability;
 
 namespace Microsoft.Agents.AI.Workflows.Execution;
 
@@ -15,6 +17,9 @@ namespace Microsoft.Agents.AI.Workflows.Execution;
 /// </summary>
 internal sealed class StreamingRunEventStream : IRunEventStream
 {
+    private static readonly string s_namespace = typeof(StreamingRunEventStream).Namespace!;
+    private static readonly ActivitySource s_activitySource = new(s_namespace);
+
     private readonly Channel<WorkflowEvent> _eventChannel;
     private readonly ISuperStepRunner _stepRunner;
     private readonly InputWaiter _inputWaiter;
@@ -58,6 +63,9 @@ internal sealed class StreamingRunEventStream : IRunEventStream
         // Subscribe to events - they will flow directly to the channel as they're raised
         this._stepRunner.OutgoingEvents.EventRaised += OnEventRaisedAsync;
 
+        using Activity? activity = s_activitySource.StartActivity(ActivityNames.WorkflowRun);
+        activity?.SetTag(Tags.WorkflowId, this._stepRunner.StartExecutorId).SetTag(Tags.RunId, this._stepRunner.RunId);
+
         try
         {
             // Wait for the first input before starting
@@ -65,6 +73,7 @@ internal sealed class StreamingRunEventStream : IRunEventStream
             await this._inputWaiter.WaitForInputAsync(cancellationToken: linkedSource.Token).ConfigureAwait(false);
 
             this._runStatus = RunStatus.Running;
+            activity?.AddEvent(new ActivityEvent(EventNames.WorkflowStarted));
 
             while (!linkedSource.Token.IsCancellationRequested)
             {
@@ -99,9 +108,17 @@ internal sealed class StreamingRunEventStream : IRunEventStream
         {
             // Expected during shutdown
         }
-        catch (Exception e)
+        catch (Exception ex)
         {
-            await this._eventChannel.Writer.WriteAsync(new WorkflowErrorEvent(e), linkedSource.Token).ConfigureAwait(false);
+            if (activity != null)
+            {
+                activity.AddEvent(new ActivityEvent(EventNames.WorkflowError, tags: new() {
+                             { Tags.ErrorType, ex.GetType().FullName },
+                             { Tags.BuildErrorMessage, ex.Message },
+                        }));
+                activity.CaptureException(ex);
+            }
+            await this._eventChannel.Writer.WriteAsync(new WorkflowErrorEvent(ex), linkedSource.Token).ConfigureAwait(false);
         }
         finally
         {
@@ -110,6 +127,7 @@ internal sealed class StreamingRunEventStream : IRunEventStream
 
             // Mark as ended when run loop exits
             this._runStatus = RunStatus.Ended;
+            activity?.AddEvent(new ActivityEvent(EventNames.WorkflowCompleted));
         }
 
         async ValueTask OnEventRaisedAsync(object? sender, WorkflowEvent e)

dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj

@@ -32,7 +32,7 @@
 
   <ItemGroup>
     <InternalsVisibleTo Include="Microsoft.Agents.AI.UnitTests" />
-    <InternalsVisibleTo Include="DynamicProxyGenAssembly2, PublicKey=0024000004800000940000000602000000240000525341310004000001000100c547cac37abd99c8db225ef2f6c8a3602f3b3606cc9891605d02baa56104f4cfc0734aa39b93bf7852f7d9266654753cc297e7d2edfe0bac1cdcf9f717241550e0a7b191195b7667bb4f64bcb8e2121380fd1d9d46ad2d92d2d15605093924cceaf74c4861eff62abf69b9291ed0a340e113be11e6a7d3113e92484cf7045cc7"/>
+    <InternalsVisibleTo Include="DynamicProxyGenAssembly2" />
   </ItemGroup>
 
 </Project>

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/MockAgentProvider.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Moq;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative.UnitTests;
+
+/// <summary>
+/// Mock implementation of <see cref="WorkflowAgentProvider"/> for unit testing purposes.
+/// </summary>
+internal sealed class MockAgentProvider : Mock<WorkflowAgentProvider>
+{
+    public IList<string> ExistingConversationIds { get; } = [];
+
+    public MockAgentProvider()
+    {
+        this.Setup(provider => provider.CreateConversationAsync(It.IsAny<CancellationToken>()))
+            .Returns(() => Task.FromResult(this.CreateConversationId()));
+    }
+
+    private string CreateConversationId()
+    {
+        string newConversationId = Guid.NewGuid().ToString("N");
+        this.ExistingConversationIds.Add(newConversationId);
+
+        return newConversationId;
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/ObjectModel/CreateConversationExecutorTest.cs

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Linq;
+using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
+using Microsoft.Agents.AI.Workflows.Declarative.PowerFx;
+using Microsoft.Bot.ObjectModel;
+using Microsoft.PowerFx.Types;
+using Xunit.Abstractions;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative.UnitTests.ObjectModel;
+
+/// <summary>
+/// Tests for <see cref="CreateConversationExecutor "/>.
+/// </summary>
+public sealed class CreateConversationExecutorTest(ITestOutputHelper output) : WorkflowActionExecutorTest(output)
+{
+    [Fact]
+    public async Task CreateNewConversationAsync()
+    {
+        // Arrange, Act, Assert
+        await this.ExecuteTestAsync(nameof(CreateNewConversationAsync),
+            "TestConversationId",
+            executionIteration: 1);
+    }
+
+    [Fact]
+    public async Task CreateMultipleConversationsAsync()
+    {
+        // Arrange, Act, Assert
+        await this.ExecuteTestAsync(nameof(CreateMultipleConversationsAsync),
+            "TestConversationId",
+            executionIteration: 4);
+    }
+
+    private async Task ExecuteTestAsync(
+        string displayName,
+        string variableName,
+        int executionIteration)
+    {
+        // Arrange
+        // Initialize state to simulate workflow environment.
+        this.State.InitializeSystem();
+        CreateConversation model = this.CreateModel(
+            this.FormatDisplayName(displayName),
+            FormatVariablePath(variableName));
+        MockAgentProvider mockAgentProvider = new();
+        CreateConversationExecutor action = new(model, mockAgentProvider.Object, this.State);
+
+        // Act
+        int expectedIterationCount = executionIteration;
+        while (executionIteration-- > 0)
+        {
+            await this.ExecuteAsync(action);
+        }
+
+        // Assert
+        VerifyModel(model, action);
+        Assert.Equal(expected: expectedIterationCount, actual: mockAgentProvider.ExistingConversationIds.Count);
+        this.VerifyState("TestConversationId", FormulaValue.New(mockAgentProvider.ExistingConversationIds.Last()));
+    }
+
+    private CreateConversation CreateModel(string displayName, string conversationIdVariable)
+    {
+        CreateConversation.Builder actionBuilder =
+            new()
+            {
+                Id = this.CreateActionId(),
+                DisplayName = this.FormatDisplayName(displayName),
+                ConversationId = PropertyPath.Create(conversationIdVariable)
+            };
+
+        return AssignParent<CreateConversation>(actionBuilder);
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/ObservabilityTests.cs

@@ -0,0 +1,186 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Linq;
+using System.Threading.Tasks;
+using FluentAssertions;
+using Microsoft.Agents.AI.Workflows.InProc;
+using Microsoft.Agents.AI.Workflows.Observability;
+
+namespace Microsoft.Agents.AI.Workflows.UnitTests;
+
+/// <summary>
+/// These tests ensure that OpenTelemetry Activity traces are properly created for workflow monitoring.
+/// Tests are run in a collection to avoid parallel execution since ActivityListener is global.
+/// Each test creates a new instance of ObservabilityTests and runs in serial within the collection.
+/// This prevents interference between tests due to the global nature of ActivityListener.
+/// </summary>
+[Collection("ObservabilityTests")]
+public sealed class ObservabilityTests : IDisposable
+{
+    private readonly ActivityListener _activityListener;
+    private readonly ConcurrentBag<Activity> _capturedActivities = [];
+
+    private bool _isDisposed;
+
+    public ObservabilityTests()
+    {
+        // Set up activity listener to capture activities from workflow
+        // This is global and captures ALL workflow activities from ANY test in the same process!
+        this._activityListener = new ActivityListener
+        {
+            ShouldListenTo = source => source.Name.Contains(typeof(Workflow).Namespace!),
+            Sample = (ref ActivityCreationOptions<ActivityContext> options) => ActivitySamplingResult.AllData,
+            ActivityStarted = activity => this._capturedActivities.Add(activity),
+        };
+        ActivitySource.AddActivityListener(this._activityListener);
+    }
+
+    /// <summary>
+    /// Create a sample workflow for testing.
+    /// </summary>
+    /// <remarks>
+    /// This workflow is expected to create 8 activities that will be captured by the tests
+    /// - ActivityNames.WorkflowBuild
+    /// - ActivityNames.WorkflowRun
+    /// -- ActivityNames.EdgeGroupProcess
+    /// -- ActivityNames.ExecutorProcess (UppercaseExecutor)
+    /// --- ActivityNames.MessageSend
+    /// ---- ActivityNames.EdgeGroupProcess
+    /// -- ActivityNames.ExecutorProcess (ReverseTextExecutor)
+    /// --- ActivityNames.MessageSend
+    /// </remarks>
+    /// <returns>The created workflow.</returns>
+    private static Workflow CreateWorkflow()
+    {
+        // Create the executors
+        Func<string, string> uppercaseFunc = s => s.ToUpperInvariant();
+        var uppercase = uppercaseFunc.BindAsExecutor("UppercaseExecutor");
+
+        Func<string, string> reverseFunc = s => new string(s.Reverse().ToArray());
+        var reverse = reverseFunc.BindAsExecutor("ReverseTextExecutor");
+
+        // Build the workflow by connecting executors sequentially
+        WorkflowBuilder builder = new(uppercase);
+        builder.AddEdge(uppercase, reverse).WithOutputFrom(reverse);
+
+        return builder.Build();
+    }
+
+    private static Dictionary<string, int> GetExpectedActivityNameCounts() =>
+        new()
+        {
+            { ActivityNames.WorkflowBuild, 1 },
+            { ActivityNames.WorkflowRun, 1 },
+            { ActivityNames.EdgeGroupProcess, 2 },
+            { ActivityNames.ExecutorProcess, 2 },
+            { ActivityNames.MessageSend, 2 }
+        };
+
+    private static InProcessExecutionEnvironment GetExecutionEnvironment(string name) =>
+        name switch
+        {
+            "Default" => InProcessExecution.Default,
+            "Lockstep" => InProcessExecution.Lockstep,
+            "OffThread" => InProcessExecution.OffThread,
+            "Concurrent" => InProcessExecution.Concurrent,
+            _ => throw new ArgumentException($"Unknown execution environment name: {name}")
+        };
+
+    public void Dispose()
+    {
+        if (!this._isDisposed)
+        {
+            this._activityListener?.Dispose();
+            this._isDisposed = true;
+        }
+    }
+
+    private async Task TestWorkflowEndToEndActivitiesAsync(string executionEnvironmentName)
+    {
+        // Arrange
+        // Create a test activity to correlate captured activities
+        using var testActivity = new Activity("ObservabilityTest").Start();
+
+        // Act
+        var workflow = CreateWorkflow();
+        var executionEnvironment = GetExecutionEnvironment(executionEnvironmentName);
+        Run run = await executionEnvironment.RunAsync(workflow, "Hello, World!");
+        await run.DisposeAsync();
+
+        await Task.Delay(100); // Allow time for activities to be captured
+
+        // Assert
+        var capturedActivities = this._capturedActivities.Where(a => a.RootId == testActivity.RootId).ToList();
+        capturedActivities.Should().HaveCount(8, "Exactly 8 activities should be created.");
+
+        // Make sure all expected activities exist and have the correct count
+        foreach (var kvp in GetExpectedActivityNameCounts())
+        {
+            var activityName = kvp.Key;
+            var expectedCount = kvp.Value;
+            var actualCount = capturedActivities.Count(a => a.OperationName == activityName);
+            actualCount.Should().Be(expectedCount, $"Activity '{activityName}' should occur {expectedCount} times.");
+        }
+
+        // Verify WorkflowRun activity events include workflow lifecycle events
+        var workflowRunActivity = capturedActivities.First(a => a.OperationName == ActivityNames.WorkflowRun);
+        var activityEvents = workflowRunActivity.Events.ToList();
+        activityEvents.Should().Contain(e => e.Name == EventNames.WorkflowStarted, "activity should have workflow started event");
+        activityEvents.Should().Contain(e => e.Name == EventNames.WorkflowCompleted, "activity should have workflow completed event");
+    }
+
+    [Fact]
+    public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_DefaultAsync()
+    {
+        await this.TestWorkflowEndToEndActivitiesAsync("Default");
+    }
+
+    [Fact]
+    public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_OffThreadAsync()
+    {
+        await this.TestWorkflowEndToEndActivitiesAsync("OffThread");
+    }
+
+    [Fact]
+    public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_ConcurrentAsync()
+    {
+        await this.TestWorkflowEndToEndActivitiesAsync("Concurrent");
+    }
+
+    [Fact]
+    public async Task CreatesWorkflowEndToEndActivities_WithCorrectName_LockstepAsync()
+    {
+        await this.TestWorkflowEndToEndActivitiesAsync("Lockstep");
+    }
+
+    [Fact]
+    public async Task CreatesWorkflowActivities_WithCorrectNameAsync()
+    {
+        // Arrange
+        // Create a test activity to correlate captured activities
+        using var testActivity = new Activity("ObservabilityTest").Start();
+
+        // Act
+        CreateWorkflow();
+        await Task.Delay(100); // Allow time for activities to be captured
+
+        // Assert
+        var capturedActivities = this._capturedActivities.Where(a => a.RootId == testActivity.RootId).ToList();
+        capturedActivities.Should().HaveCount(1, "Exactly 1 activity should be created.");
+        capturedActivities[0].OperationName.Should().Be(ActivityNames.WorkflowBuild,
+            "The activity should have the correct operation name for workflow build.");
+
+        var events = capturedActivities[0].Events.ToList();
+        events.Should().Contain(e => e.Name == EventNames.BuildStarted, "activity should have build started event");
+        events.Should().Contain(e => e.Name == EventNames.BuildValidationCompleted, "activity should have build validation completed event");
+        events.Should().Contain(e => e.Name == EventNames.BuildCompleted, "activity should have build completed event");
+
+        var tags = capturedActivities[0].Tags.ToDictionary(t => t.Key, t => t.Value);
+        tags.Should().ContainKey(Tags.WorkflowId);
+        tags.Should().ContainKey(Tags.WorkflowDefinition);
+    }
+}

python/.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
       - id: check-json
         name: Check JSON files
         files: \.json$
-        exclude: ^.*\.vscode\/.*
+        exclude: ^.*\.vscode\/.*|^python/demos/samples/chatkit-integration/frontend/(tsconfig.*\.json|package-lock\.json)$
       - id: end-of-file-fixer
         name: Fix End of File
         files: \.py$

python/.vscode/launch.json

@@ -12,6 +12,15 @@
             "console": "integratedTerminal",
             "justMyCode": false
         },
+        {
+            "name": "AG-UI Examples Server",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "examples",
+            "cwd": "${workspaceFolder}/packages/ag-ui",
+            "console": "integratedTerminal",
+            "justMyCode": false
+        },
         {
             "name": "Python Attach",
             "type": "debugpy",

python/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0b251105] - 2025-11-05
+
+### Added
+
+- **agent-framework-ag-ui**: Initial release of AG-UI protocol integration for Agent Framework ([#1826](https://github.com/microsoft/agent-framework/pull/1826))
+
+## [1.0.0b251104] - 2025-11-04
+
+### Added
+
+- Introducing the Anthropic Client ([#1819](https://github.com/microsoft/agent-framework/pull/1819))
+
+### Changed
+
+- [BREAKING] Consolidate workflow run APIs ([#1723](https://github.com/microsoft/agent-framework/pull/1723))
+- [BREAKING] Remove request_type param from ctx.request_info() ([#1824](https://github.com/microsoft/agent-framework/pull/1824))
+- [BREAKING] Cleanup of dependencies ([#1803](https://github.com/microsoft/agent-framework/pull/1803))
+- [BREAKING] Replace `RequestInfoExecutor` with `request_info` API and `@response_handler` ([#1466](https://github.com/microsoft/agent-framework/pull/1466))
+- Azure AI Search Support Update + Refactored Samples & Unit Tests ([#1683](https://github.com/microsoft/agent-framework/pull/1683))
+- Lab: Updates to GAIA module ([#1763](https://github.com/microsoft/agent-framework/pull/1763))
+
+### Fixed
+
+- Azure AI `top_p` and `temperature` parameters fix ([#1839](https://github.com/microsoft/agent-framework/pull/1839))
+- Ensure agent thread is part of checkpoint ([#1756](https://github.com/microsoft/agent-framework/pull/1756))
+- Fix middleware and cleanup confusing function ([#1865](https://github.com/microsoft/agent-framework/pull/1865))
+- Fix type compatibility check ([#1753](https://github.com/microsoft/agent-framework/pull/1753))
+- Fix mcp tool cloning for handoff pattern ([#1883](https://github.com/microsoft/agent-framework/pull/1883))
+
 ## [1.0.0b251028] - 2025-10-28
 
 ### Added
@@ -124,7 +153,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.0b251028...HEAD
+[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251104...HEAD
+[1.0.0b251104]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251028...python-1.0.0b251104
 [1.0.0b251028]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251016...python-1.0.0b251028
 [1.0.0b251016]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251007...python-1.0.0b251016
 [1.0.0b251007]: https://github.com/microsoft/agent-framework/compare/python-1.0.0b251001...python-1.0.0b251007

python/README.md

@@ -233,7 +233,7 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-**Note**: Advanced orchestration patterns like GroupChat, Sequential, and Concurrent orchestrations are coming soon.
+For more advanced orchestration patterns including Sequential, GroupChat, Concurrent, Magentic, and Handoff orchestrations, see the [orchestration samples](samples/getting_started/workflows/orchestration).
 
 ## More Examples & Samples
 

python/packages/a2a/pyproject.toml

@@ -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.0b251028"
+version = "1.0.0b251104"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/ag-ui/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python/packages/ag-ui/README.md

@@ -0,0 +1,71 @@
+# Agent Framework AG-UI Integration
+
+AG-UI protocol integration for Agent Framework, enabling seamless integration with AG-UI's web interface and streaming protocol.
+
+## Installation
+
+```bash
+pip install agent-framework-ag-ui
+```
+
+## Quick Start
+
+```python
+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
+
+# Create your agent
+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",
+    ),
+)
+
+# Create FastAPI app and add AG-UI endpoint
+app = FastAPI()
+add_agent_framework_fastapi_endpoint(app, agent, "/")
+
+# Run with: uvicorn main:app --reload
+```
+
+## Documentation
+
+- **[Getting Started Tutorial](getting_started/)** - Step-by-step guide to building your first AG-UI server and client
+- **[Examples](examples/)** - Complete examples for AG-UI features
+
+## Features
+
+This integration supports all 7 AG-UI features:
+
+1. **Agentic Chat**: Basic streaming chat with tool calling support
+2. **Backend Tool Rendering**: Tools executed on backend with results streamed to client
+3. **Human in the Loop**: Function approval requests for user confirmation before tool execution
+4. **Agentic Generative UI**: Async tools for long-running operations with progress updates
+5. **Tool-based Generative UI**: Custom UI components rendered on frontend based on tool calls
+6. **Shared State**: Bidirectional state sync between client and server
+7. **Predictive State Updates**: Stream tool arguments as optimistic state updates during execution
+
+## Architecture
+
+The package uses a clean, orchestrator-based architecture:
+
+- **AgentFrameworkAgent**: Lightweight wrapper that delegates to orchestrators
+- **Orchestrators**: Handle different execution flows (default, human-in-the-loop, etc.)
+- **Confirmation Strategies**: Domain-specific confirmation messages (extensible)
+- **AgentFrameworkEventBridge**: Converts Agent Framework events to AG-UI events
+- **Message Adapters**: Bidirectional conversion between AG-UI and Agent Framework message formats
+- **FastAPI Endpoint**: Streaming HTTP endpoint with Server-Sent Events (SSE)
+
+## Next Steps
+
+1. **New to AG-UI?** Start with the [Getting Started Tutorial](getting_started/)
+2. **Want to see examples?** Check out the [Examples](examples/) for AG-UI features
+
+## License
+
+MIT

python/packages/ag-ui/agent_framework_ag_ui/__init__.py

@@ -0,0 +1,31 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""AG-UI protocol integration for Agent Framework."""
+
+import importlib.metadata
+
+from ._agent import AgentFrameworkAgent
+from ._confirmation_strategies import (
+    ConfirmationStrategy,
+    DefaultConfirmationStrategy,
+    DocumentWriterConfirmationStrategy,
+    RecipeConfirmationStrategy,
+    TaskPlannerConfirmationStrategy,
+)
+from ._endpoint import add_agent_framework_fastapi_endpoint
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AgentFrameworkAgent",
+    "add_agent_framework_fastapi_endpoint",
+    "ConfirmationStrategy",
+    "DefaultConfirmationStrategy",
+    "TaskPlannerConfirmationStrategy",
+    "RecipeConfirmationStrategy",
+    "DocumentWriterConfirmationStrategy",
+    "__version__",
+]

python/packages/ag-ui/agent_framework_ag_ui/_agent.py

@@ -0,0 +1,160 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""AgentFrameworkAgent wrapper for AG-UI protocol - Clean Architecture."""
+
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from ag_ui.core import BaseEvent
+from agent_framework import AgentProtocol
+
+from ._confirmation_strategies import ConfirmationStrategy, DefaultConfirmationStrategy
+from ._orchestrators import (
+    DefaultOrchestrator,
+    ExecutionContext,
+    HumanInTheLoopOrchestrator,
+    Orchestrator,
+)
+
+
+class AgentConfig:
+    """Configuration for agent wrapper."""
+
+    def __init__(
+        self,
+        state_schema: dict[str, Any] | None = None,
+        predict_state_config: dict[str, dict[str, str]] | None = None,
+        require_confirmation: bool = True,
+    ):
+        """Initialize agent configuration.
+
+        Args:
+            state_schema: Optional state schema for state management
+            predict_state_config: Configuration for predictive state updates
+            require_confirmation: Whether predictive updates require confirmation
+        """
+        self.state_schema = state_schema or {}
+        self.predict_state_config = predict_state_config or {}
+        self.require_confirmation = require_confirmation
+
+
+class AgentFrameworkAgent:
+    """Wraps Agent Framework agents for AG-UI protocol compatibility.
+
+    Translates between Agent Framework's AgentProtocol and AG-UI's event-based
+    protocol. Uses orchestrators to handle different execution flows (standard
+    execution, human-in-the-loop, etc.). Orchestrators are checked in order;
+    the first matching orchestrator handles the request.
+
+    Supports predictive state updates for agentic generative UI, with optional
+    confirmation requirements configurable per use case.
+    """
+
+    def __init__(
+        self,
+        agent: AgentProtocol,
+        name: str | None = None,
+        description: str | None = None,
+        state_schema: dict[str, Any] | None = None,
+        predict_state_config: dict[str, dict[str, str]] | None = None,
+        require_confirmation: bool = True,
+        orchestrators: list[Orchestrator] | None = None,
+        confirmation_strategy: ConfirmationStrategy | None = None,
+    ):
+        """Initialize the AG-UI compatible agent wrapper.
+
+        Args:
+            agent: The Agent Framework agent to wrap
+            name: Optional name for the agent
+            description: Optional description
+            state_schema: Optional state schema for state management
+            predict_state_config: Configuration for predictive state updates.
+                Format: {"state_key": {"tool": "tool_name", "tool_argument": "arg_name"}}
+            require_confirmation: Whether predictive updates require confirmation.
+                Set to False for agentic generative UI that updates automatically.
+            orchestrators: Custom orchestrators (auto-configured if None).
+                Orchestrators are checked in order; first match handles the request.
+            confirmation_strategy: Strategy for generating confirmation messages.
+                Defaults to DefaultConfirmationStrategy if None.
+        """
+        self.agent = agent
+        self.name = name or getattr(agent, "name", "agent")
+        self.description = description or getattr(agent, "description", "")
+
+        self.config = AgentConfig(
+            state_schema=state_schema,
+            predict_state_config=predict_state_config,
+            require_confirmation=require_confirmation,
+        )
+
+        # Configure orchestrators
+        if orchestrators is None:
+            self.orchestrators = self._default_orchestrators()
+        else:
+            self.orchestrators = orchestrators
+
+        # Configure confirmation strategy
+        if confirmation_strategy is None:
+            self.confirmation_strategy: ConfirmationStrategy = DefaultConfirmationStrategy()
+        else:
+            self.confirmation_strategy = confirmation_strategy
+
+    def _default_orchestrators(self) -> list[Orchestrator]:
+        """Create default orchestrator chain.
+
+        Returns:
+            List of orchestrators in priority order. First matching orchestrator
+            handles the request, so order matters.
+        """
+        return [
+            HumanInTheLoopOrchestrator(),  # Handle tool approval responses
+            # Add more specialized orchestrators here as needed
+            DefaultOrchestrator(),  # Fallback: standard agent execution
+        ]
+
+    async def run_agent(
+        self,
+        input_data: dict[str, Any],
+    ) -> AsyncGenerator[BaseEvent, None]:
+        """Run the agent and yield AG-UI events.
+
+        This is the ONLY public method - much simpler than the original 376-line
+        implementation. All orchestration logic has been extracted into dedicated
+        Orchestrator classes.
+
+        The method creates an ExecutionContext with all needed data, then finds
+        the first orchestrator that can handle the request and delegates to it.
+
+        Args:
+            input_data: The AG-UI run input containing messages, state, etc.
+
+        Yields:
+            AG-UI events
+
+        Raises:
+            RuntimeError: If no orchestrator matches (should never happen if
+                DefaultOrchestrator is last in the chain)
+        """
+        # Create execution context with all needed data
+        context = ExecutionContext(
+            input_data=input_data,
+            agent=self.agent,
+            config=self.config,
+            confirmation_strategy=self.confirmation_strategy,
+        )
+
+        # Find matching orchestrator and execute
+        for orchestrator in self.orchestrators:
+            if orchestrator.can_handle(context):
+                async for event in orchestrator.run(context):
+                    yield event
+                return
+
+        # Should never reach here if DefaultOrchestrator is last
+        raise RuntimeError("No orchestrator matched - check configuration")
+
+
+__all__ = [
+    "AgentFrameworkAgent",
+    "AgentConfig",
+]

python/packages/ag-ui/agent_framework_ag_ui/_confirmation_strategies.py

@@ -0,0 +1,175 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Confirmation strategies for human-in-the-loop approval flows.
+
+Each agent can provide a custom confirmation strategy to generate domain-specific
+messages when users approve or reject changes/actions.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class ConfirmationStrategy(ABC):
+    """Strategy for generating confirmation messages during human-in-the-loop flows."""
+
+    @abstractmethod
+    def on_approval_accepted(self, steps: list[dict[str, Any]]) -> str:
+        """Generate message when user approves function execution.
+
+        Args:
+            steps: List of approved steps with 'description', 'status', etc.
+
+        Returns:
+            Message to display to user
+        """
+        ...
+
+    @abstractmethod
+    def on_approval_rejected(self, steps: list[dict[str, Any]]) -> str:
+        """Generate message when user rejects function execution.
+
+        Args:
+            steps: List of rejected steps
+
+        Returns:
+            Message to display to user
+        """
+        ...
+
+    @abstractmethod
+    def on_state_confirmed(self) -> str:
+        """Generate message when user confirms predictive state changes.
+
+        Returns:
+            Message to display to user
+        """
+        ...
+
+    @abstractmethod
+    def on_state_rejected(self) -> str:
+        """Generate message when user rejects predictive state changes.
+
+        Returns:
+            Message to display to user
+        """
+        ...
+
+
+class DefaultConfirmationStrategy(ConfirmationStrategy):
+    """Generic confirmation messages suitable for most agents.
+
+    This preserves the original behavior from v1.
+    """
+
+    def on_approval_accepted(self, steps: list[dict[str, Any]]) -> str:
+        """Generate generic approval message with step list."""
+        enabled_steps = [s for s in steps if s.get("status") == "enabled"]
+
+        message_parts = [f"Executing {len(enabled_steps)} approved steps:\n\n"]
+
+        for i, step in enumerate(enabled_steps, 1):
+            message_parts.append(f"{i}. {step['description']}\n")
+
+        message_parts.append("\nAll steps completed successfully!")
+
+        return "".join(message_parts)
+
+    def on_approval_rejected(self, steps: list[dict[str, Any]]) -> str:
+        """Generate generic rejection message."""
+        return "No problem! What would you like me to change about the plan?"
+
+    def on_state_confirmed(self) -> str:
+        """Generate generic state confirmation message."""
+        return "Changes confirmed and applied successfully!"
+
+    def on_state_rejected(self) -> str:
+        """Generate generic state rejection message."""
+        return "No problem! What would you like me to change?"
+
+
+class TaskPlannerConfirmationStrategy(ConfirmationStrategy):
+    """Domain-specific confirmation messages for task planning agents."""
+
+    def on_approval_accepted(self, steps: list[dict[str, Any]]) -> str:
+        """Generate task-specific approval message."""
+        enabled_steps = [s for s in steps if s.get("status") == "enabled"]
+
+        message_parts = ["Executing your requested tasks:\n\n"]
+
+        for i, step in enumerate(enabled_steps, 1):
+            message_parts.append(f"{i}. {step['description']}\n")
+
+        message_parts.append("\nAll tasks completed successfully!")
+
+        return "".join(message_parts)
+
+    def on_approval_rejected(self, steps: list[dict[str, Any]]) -> str:
+        """Generate task-specific rejection message."""
+        return "No problem! Let me revise the plan. What would you like me to change?"
+
+    def on_state_confirmed(self) -> str:
+        """Task planners typically don't use state confirmation."""
+        return "Tasks confirmed and ready to execute!"
+
+    def on_state_rejected(self) -> str:
+        """Task planners typically don't use state confirmation."""
+        return "No problem! How should I adjust the task list?"
+
+
+class RecipeConfirmationStrategy(ConfirmationStrategy):
+    """Domain-specific confirmation messages for recipe agents."""
+
+    def on_approval_accepted(self, steps: list[dict[str, Any]]) -> str:
+        """Generate recipe-specific approval message."""
+        enabled_steps = [s for s in steps if s.get("status") == "enabled"]
+
+        message_parts = ["Updating your recipe:\n\n"]
+
+        for i, step in enumerate(enabled_steps, 1):
+            message_parts.append(f"{i}. {step['description']}\n")
+
+        message_parts.append("\nRecipe updated successfully!")
+
+        return "".join(message_parts)
+
+    def on_approval_rejected(self, steps: list[dict[str, Any]]) -> str:
+        """Generate recipe-specific rejection message."""
+        return "No problem! What ingredients or steps should I change?"
+
+    def on_state_confirmed(self) -> str:
+        """Generate recipe-specific state confirmation message."""
+        return "Recipe changes applied successfully!"
+
+    def on_state_rejected(self) -> str:
+        """Generate recipe-specific state rejection message."""
+        return "No problem! What would you like me to adjust in the recipe?"
+
+
+class DocumentWriterConfirmationStrategy(ConfirmationStrategy):
+    """Domain-specific confirmation messages for document writing agents."""
+
+    def on_approval_accepted(self, steps: list[dict[str, Any]]) -> str:
+        """Generate document-specific approval message."""
+        enabled_steps = [s for s in steps if s.get("status") == "enabled"]
+
+        message_parts = ["Applying your edits:\n\n"]
+
+        for i, step in enumerate(enabled_steps, 1):
+            message_parts.append(f"{i}. {step['description']}\n")
+
+        message_parts.append("\nDocument updated successfully!")
+
+        return "".join(message_parts)
+
+    def on_approval_rejected(self, steps: list[dict[str, Any]]) -> str:
+        """Generate document-specific rejection message."""
+        return "No problem! Which changes should I keep or modify?"
+
+    def on_state_confirmed(self) -> str:
+        """Generate document-specific state confirmation message."""
+        return "Document edits applied!"
+
+    def on_state_rejected(self) -> str:
+        """Generate document-specific state rejection message."""
+        return "No problem! What should I change about the document?"

python/packages/ag-ui/agent_framework_ag_ui/_endpoint.py

@@ -0,0 +1,94 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""FastAPI endpoint creation for AG-UI agents."""
+
+import logging
+from typing import Any
+
+from ag_ui.encoder import EventEncoder
+from agent_framework import AgentProtocol
+from fastapi import FastAPI, Request
+from fastapi.responses import StreamingResponse
+
+from ._agent import AgentFrameworkAgent
+
+logger = logging.getLogger(__name__)
+
+
+def add_agent_framework_fastapi_endpoint(
+    app: FastAPI,
+    agent: AgentProtocol | AgentFrameworkAgent,
+    path: str = "/",
+    state_schema: dict[str, Any] | None = None,
+    predict_state_config: dict[str, dict[str, str]] | None = None,
+    allow_origins: list[str] | None = None,
+) -> None:
+    """Add an AG-UI endpoint to a FastAPI app.
+
+    Args:
+        app: The FastAPI application
+        agent: The agent to expose (can be raw AgentProtocol or wrapped)
+        path: The endpoint path
+        state_schema: Optional state schema for shared state management
+        predict_state_config: Optional predictive state update configuration.
+            Format: {"state_key": {"tool": "tool_name", "tool_argument": "arg_name"}}
+        allow_origins: CORS origins (not yet implemented)
+    """
+    if isinstance(agent, AgentProtocol):
+        wrapped_agent = AgentFrameworkAgent(
+            agent=agent,
+            state_schema=state_schema,
+            predict_state_config=predict_state_config,
+        )
+    else:
+        wrapped_agent = agent
+
+    @app.post(path)
+    async def agent_endpoint(request: Request):  # type: ignore[misc]
+        """Handle AG-UI agent requests.
+
+        Note: Function is accessed via FastAPI's decorator registration,
+        despite appearing unused to static analysis.
+        """
+        try:
+            input_data = await request.json()
+            logger.debug(
+                f"[{path}] Received request - Run ID: {input_data.get('run_id', 'no-run-id')}, "
+                f"Thread ID: {input_data.get('thread_id', 'no-thread-id')}, "
+                f"Messages: {len(input_data.get('messages', []))}"
+            )
+            logger.info(f"Received request at {path}: {input_data.get('run_id', 'no-run-id')}")
+
+            async def event_generator():
+                encoder = EventEncoder()
+                event_count = 0
+                async for event in wrapped_agent.run_agent(input_data):
+                    event_count += 1
+                    logger.debug(f"[{path}] Event {event_count}: {type(event).__name__}")
+
+                    # Log event payload for debugging
+                    if hasattr(event, "model_dump"):
+                        event_data = event.model_dump(exclude_none=True)
+                        logger.debug(f"[{path}] Event payload: {event_data}")
+
+                    encoded = encoder.encode(event)
+                    logger.debug(
+                        f"[{path}] Encoded as: {encoded[:200]}..."
+                        if len(encoded) > 200
+                        else f"[{path}] Encoded as: {encoded}"
+                    )
+                    yield encoded
+                logger.info(f"[{path}] Completed streaming {event_count} events")
+
+            return StreamingResponse(
+                event_generator(),
+                media_type="text/event-stream",
+                headers={
+                    "Cache-Control": "no-cache",
+                    "Connection": "keep-alive",
+                    "X-Accel-Buffering": "no",
+                },
+            )
+        except Exception as e:
+            logger.error(f"Error in agent endpoint: {e}", exc_info=True)
+            return {"error": str(e)}

python/packages/ag-ui/agent_framework_ag_ui/_events.py

@@ -0,0 +1,675 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Event bridge for converting Agent Framework events to AG-UI protocol."""
+
+import json
+import logging
+import re
+from typing import Any
+
+from ag_ui.core import (
+    BaseEvent,
+    CustomEvent,
+    EventType,
+    MessagesSnapshotEvent,
+    RunFinishedEvent,
+    RunStartedEvent,
+    StateDeltaEvent,
+    StateSnapshotEvent,
+    TextMessageContentEvent,
+    TextMessageEndEvent,
+    TextMessageStartEvent,
+    ToolCallArgsEvent,
+    ToolCallEndEvent,
+    ToolCallResultEvent,
+    ToolCallStartEvent,
+)
+from agent_framework import (
+    AgentRunResponseUpdate,
+    FunctionApprovalRequestContent,
+    FunctionCallContent,
+    FunctionResultContent,
+    TextContent,
+)
+
+from ._utils import generate_event_id
+
+logger = logging.getLogger(__name__)
+
+
+class AgentFrameworkEventBridge:
+    """Converts Agent Framework responses to AG-UI events."""
+
+    def __init__(
+        self,
+        run_id: str,
+        thread_id: str,
+        predict_state_config: dict[str, dict[str, str]] | None = None,
+        current_state: dict[str, Any] | None = None,
+        skip_text_content: bool = False,
+        input_messages: list[Any] | None = None,
+        require_confirmation: bool = True,
+    ) -> None:
+        """
+        Initialize the event bridge.
+
+        Args:
+            run_id: The run identifier.
+            thread_id: The thread identifier.
+            predict_state_config: Configuration for predictive state updates.
+                Format: {"state_key": {"tool": "tool_name", "tool_argument": "arg_name"}}
+            current_state: Reference to the current state dict for tracking updates.
+            skip_text_content: If True, skip emitting TextMessageContentEvents (for structured outputs).
+            input_messages: The input messages from the conversation history.
+            require_confirmation: Whether predictive state updates require user confirmation.
+        """
+        self.run_id = run_id
+        self.thread_id = thread_id
+        self.current_message_id: str | None = None
+        self.current_tool_call_id: str | None = None
+        self.current_tool_call_name: str | None = None  # Track the tool name across streaming chunks
+        self.predict_state_config = predict_state_config or {}
+        self.current_state = current_state or {}
+        self.pending_state_updates: dict[str, Any] = {}  # Track updates from tool calls
+        self.skip_text_content = skip_text_content
+        self.require_confirmation = require_confirmation
+
+        # For predictive state updates: accumulate streaming arguments
+        self.streaming_tool_args: str = ""  # Accumulated JSON string
+        self.last_emitted_state: dict[str, Any] = {}  # Track last emitted state to avoid duplicates
+        self.state_delta_count: int = 0  # Counter for sampling log output
+        self.should_stop_after_confirm: bool = False  # Flag to stop run after confirm_changes
+        self.suppressed_summary: str = ""  # Store LLM summary to show after confirmation
+
+        # For MessagesSnapshotEvent: track tool calls and results
+        self.input_messages = input_messages or []
+        self.pending_tool_calls: list[dict[str, Any]] = []  # Track tool calls for assistant message
+        self.tool_results: list[dict[str, Any]] = []  # Track tool results
+
+    async def from_agent_run_update(self, update: AgentRunResponseUpdate) -> list[BaseEvent]:
+        """
+        Convert an AgentRunResponseUpdate to AG-UI events.
+
+        Args:
+            update: The agent run update to convert.
+
+        Returns:
+            List of AG-UI events.
+        """
+        events: list[BaseEvent] = []
+
+        for content in update.contents:
+            if isinstance(content, TextContent):
+                # Skip text content if using structured outputs (it's just the JSON)
+                if self.skip_text_content:
+                    continue
+
+                # 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")
+                    # Save the summary text to show after confirmation
+                    self.suppressed_summary += content.text
+                    continue
+
+                if not self.current_message_id:
+                    self.current_message_id = generate_event_id()
+                    start_event = TextMessageStartEvent(
+                        message_id=self.current_message_id,
+                        role="assistant",
+                    )
+                    events.append(start_event)
+
+                event = TextMessageContentEvent(
+                    message_id=self.current_message_id,
+                    delta=content.text,
+                )
+                events.append(event)
+
+            elif isinstance(content, FunctionCallContent):
+                # Log tool calls for debugging
+                if content.name:
+                    logger.debug(f"Tool call: {content.name} (call_id: {content.call_id})")
+
+                if not content.name and not content.call_id and not self.current_tool_call_name:
+                    args_preview = str(content.arguments)[:50] if content.arguments else "None"
+                    logger.warning(f"FunctionCallContent missing name and call_id. Args: {args_preview}")
+
+                # Get or use existing tool call ID - all chunks of same tool call share the same call_id
+                # Important: the first chunk might have name but no call_id yet
+                if content.call_id:
+                    tool_call_id = content.call_id
+                elif self.current_tool_call_id:
+                    tool_call_id = self.current_tool_call_id
+                else:
+                    # Generate a new ID for this tool call
+                    tool_call_id = (
+                        generate_event_id()
+                    )  # Handle streaming tool calls - name comes in first chunk, arguments in subsequent chunks
+                if content.name:
+                    # This is a new tool call or the first chunk with the name
+                    self.current_tool_call_id = tool_call_id
+                    self.current_tool_call_name = content.name
+
+                    tool_start_event = ToolCallStartEvent(
+                        tool_call_id=tool_call_id,
+                        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}'")
+                    events.append(tool_start_event)
+
+                    # Track tool call for MessagesSnapshotEvent
+                    # Initialize a new tool call entry
+                    self.pending_tool_calls.append(
+                        {
+                            "id": tool_call_id,
+                            "type": "function",
+                            "function": {
+                                "name": content.name,
+                                "arguments": "",  # Will accumulate as we get argument chunks
+                            },
+                        }
+                    )
+                else:
+                    # Subsequent chunk without name - update our tracked ID if needed
+                    if tool_call_id:
+                        self.current_tool_call_id = tool_call_id
+
+                # Emit arguments if present
+                if content.arguments:
+                    # content.arguments is already a JSON string from the LLM for streaming calls
+                    # For non-streaming it could be a dict, so we need to handle both
+                    if isinstance(content.arguments, str):
+                        delta_str = content.arguments
+                    else:
+                        # 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}'")
+                    args_event = ToolCallArgsEvent(
+                        tool_call_id=tool_call_id,
+                        delta=delta_str,
+                    )
+                    events.append(args_event)
+
+                    # Accumulate arguments for MessagesSnapshotEvent
+                    if self.pending_tool_calls:
+                        # Find the matching tool call and append the delta
+                        for tool_call in self.pending_tool_calls:
+                            if tool_call["id"] == tool_call_id:
+                                tool_call["function"]["arguments"] += delta_str
+                                break
+
+                    # Predictive state updates - accumulate streaming arguments and emit deltas
+                    # Use current_tool_call_name since content.name is only present on first chunk
+                    if self.current_tool_call_name and self.predict_state_config:
+                        # Accumulate the argument string
+                        if isinstance(content.arguments, str):
+                            self.streaming_tool_args += content.arguments
+                        else:
+                            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}'"
+                        )
+
+                        # Try to parse accumulated arguments (may be incomplete JSON)
+                        # We use a lenient approach: try standard parsing first, then try to extract partial values
+                        parsed_args = None
+                        try:
+                            parsed_args = json.loads(self.streaming_tool_args)
+                        except json.JSONDecodeError:
+                            # JSON is incomplete - try to extract partial string values
+                            # For streaming "document" field, we can extract: {"document": "text...
+                            # Look for pattern: {"field": "value (incomplete)
+                            for state_key, config in self.predict_state_config.items():
+                                if config["tool"] == self.current_tool_call_name:
+                                    tool_arg_name = config["tool_argument"]
+
+                                    # Try to extract partial string value for this argument
+                                    # Pattern: "argument_name": "partial text
+                                    pattern = rf'"{re.escape(tool_arg_name)}":\s*"([^"]*)'
+                                    match = re.search(pattern, self.streaming_tool_args)
+
+                                    if match:
+                                        partial_value = match.group(1)
+                                        # Unescape common sequences
+                                        partial_value = (
+                                            partial_value.replace("\\n", "\n").replace('\\"', '"').replace("\\\\", "\\")
+                                        )
+
+                                        # Emit delta if we have new content
+                                        if (
+                                            state_key not in self.last_emitted_state
+                                            or self.last_emitted_state[state_key] != partial_value
+                                        ):
+                                            state_delta_event = StateDeltaEvent(
+                                                delta=[
+                                                    {
+                                                        "op": "replace",
+                                                        "path": f"/{state_key}",
+                                                        "value": partial_value,
+                                                    }
+                                                ],
+                                            )
+
+                                            self.state_delta_count += 1
+                                            if self.state_delta_count % 10 == 1:
+                                                value_preview = (
+                                                    str(partial_value)[:100] + "..."
+                                                    if len(str(partial_value)) > 100
+                                                    else str(partial_value)
+                                                )
+                                                logger.info(
+                                                    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")
+
+                                            events.append(state_delta_event)
+                                            self.last_emitted_state[state_key] = partial_value
+                                            self.pending_state_updates[state_key] = partial_value
+
+                        # If we successfully parsed complete JSON, process it
+                        if parsed_args:
+                            # Check if this tool matches any predictive state config
+                            for state_key, config in self.predict_state_config.items():
+                                if config["tool"] == self.current_tool_call_name:
+                                    tool_arg_name = config["tool_argument"]
+
+                                    # Extract the state value
+                                    if tool_arg_name == "*":
+                                        state_value = parsed_args
+                                    elif tool_arg_name in parsed_args:
+                                        state_value = parsed_args[tool_arg_name]
+                                    else:
+                                        continue
+
+                                    # Only emit if state has changed from last emission
+                                    if (
+                                        state_key not in self.last_emitted_state
+                                        or self.last_emitted_state[state_key] != state_value
+                                    ):
+                                        # Emit StateDeltaEvent for real-time UI updates (JSON Patch format)
+                                        state_delta_event = StateDeltaEvent(
+                                            delta=[
+                                                {
+                                                    "op": "replace",  # Use replace since field exists in schema
+                                                    "path": f"/{state_key}",  # JSON Pointer path with leading slash
+                                                    "value": state_value,
+                                                }
+                                            ],
+                                        )
+
+                                        # Increment counter and log every 10th emission with sample data
+                                        self.state_delta_count += 1
+                                        if self.state_delta_count % 10 == 1:  # Log 1st, 11th, 21st, etc.
+                                            value_preview = (
+                                                str(state_value)[:100] + "..."
+                                                if len(str(state_value)) > 100
+                                                else str(state_value)
+                                            )
+                                            logger.info(
+                                                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")
+
+                                        events.append(state_delta_event)
+
+                                        # Track what we emitted
+                                        self.last_emitted_state[state_key] = state_value
+                                        self.pending_state_updates[state_key] = state_value
+
+                    # Legacy predictive state check (for when arguments are complete)
+                    if content.name and content.arguments:
+                        parsed_args = content.parse_arguments()
+
+                        if parsed_args:
+                            logger.info(f"Checking predict_state_config: {self.predict_state_config}")
+                            for state_key, config in self.predict_state_config.items():
+                                logger.info(f"Checking state_key='{state_key}', config={config}")
+                                if config["tool"] == content.name:
+                                    tool_arg_name = config["tool_argument"]
+                                    logger.info(
+                                        f"MATCHED tool '{content.name}' for state key '{state_key}', arg='{tool_arg_name}'"
+                                    )
+
+                                    # If tool_argument is "*", use all arguments as the state value
+                                    if tool_arg_name == "*":
+                                        state_value = parsed_args
+                                        logger.info(f"Using all args as state value, keys: {list(state_value.keys())}")
+                                    elif tool_arg_name in parsed_args:
+                                        state_value = parsed_args[tool_arg_name]
+                                        logger.info(f"Using specific arg '{tool_arg_name}' as state value")
+                                    else:
+                                        logger.warning(f"Tool argument '{tool_arg_name}' not found in parsed args")
+                                        continue
+
+                                    # Emit predictive delta (JSON Patch format)
+                                    state_delta_event = StateDeltaEvent(
+                                        delta=[
+                                            {
+                                                "op": "replace",  # Use replace since field exists in schema
+                                                "path": f"/{state_key}",  # JSON Pointer path with leading slash
+                                                "value": state_value,
+                                            }
+                                        ],
+                                    )
+                                    logger.info(
+                                        f"  >>> Emitting StateDeltaEvent for key '{state_key}', value type: {type(state_value)}"
+                                    )
+                                    events.append(state_delta_event)
+
+                                    # Track pending update for later snapshot
+                                    self.pending_state_updates[state_key] = state_value
+
+                # Note: ToolCallEndEvent is emitted when we receive FunctionResultContent,
+                # not here during streaming, since we don't know when the stream is complete
+
+            elif isinstance(content, FunctionResultContent):
+                # First emit ToolCallEndEvent to close the tool call
+                if content.call_id:
+                    end_event = ToolCallEndEvent(
+                        tool_call_id=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"
+                        )
+
+                    # Reset streaming accumulator and counter for next tool call
+                    self.streaming_tool_args = ""
+                    self.state_delta_count = 0
+
+                # Tool result - emit ToolCallResultEvent
+                result_message_id = generate_event_id()
+
+                # Preserve structured data for backend tool rendering
+                # Serialize dicts to JSON string, otherwise convert to string
+                if isinstance(content.result, dict):
+                    result_content = json.dumps(content.result)  # type: ignore[arg-type]
+                elif content.result is not None:
+                    result_content = str(content.result)
+                else:
+                    result_content = ""
+
+                result_event = ToolCallResultEvent(
+                    message_id=result_message_id,
+                    tool_call_id=content.call_id,
+                    content=result_content,
+                    role="tool",
+                )
+                events.append(result_event)
+
+                # Track tool result for MessagesSnapshotEvent
+                self.tool_results.append(
+                    {
+                        "id": result_message_id,
+                        "role": "tool",
+                        "tool_call_id": content.call_id,
+                        "content": result_content,
+                    }
+                )
+
+                # 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:
+                    # Build assistant message with tool_calls
+                    assistant_message = {
+                        "id": generate_event_id(),
+                        "role": "assistant",
+                        "tool_calls": self.pending_tool_calls.copy(),  # Copy the accumulated tool calls
+                    }
+
+                    # Build complete messages array: input messages + assistant message + tool results
+                    all_messages = list(self.input_messages) + [assistant_message] + self.tool_results.copy()
+
+                    # Emit MessagesSnapshotEvent using the proper event type
+                    messages_snapshot_event = MessagesSnapshotEvent(
+                        type=EventType.MESSAGES_SNAPSHOT, messages=all_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
+                if self.pending_state_updates:
+                    # Update the current state with pending updates
+                    for key, value in self.pending_state_updates.items():
+                        self.current_state[key] = value
+
+                    # Log the state structure for debugging
+                    logger.info(f"Emitting StateSnapshotEvent with keys: {list(self.current_state.keys())}")
+                    if "recipe" in self.current_state:
+                        recipe = self.current_state["recipe"]
+                        logger.info(
+                            f"Recipe fields: title={recipe.get('title')}, "
+                            f"skill_level={recipe.get('skill_level')}, "
+                            f"ingredients_count={len(recipe.get('ingredients', []))}, "
+                            f"instructions_count={len(recipe.get('instructions', []))}"
+                        )
+
+                    # Emit complete state snapshot
+                    state_snapshot_event = StateSnapshotEvent(
+                        snapshot=self.current_state,
+                    )
+                    events.append(state_snapshot_event)
+
+                    # Check if this was a predictive state update tool (e.g., write_document_local)
+                    # 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"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():
+                        # Check if this tool call matches a predictive config
+                        # 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}'"
+                            )
+                            tool_was_predictive = True
+                            break
+
+                    if tool_was_predictive and self.require_confirmation:
+                        # Emit confirm_changes tool call sequence
+                        confirm_call_id = generate_event_id()
+
+                        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(
+                            {
+                                "id": confirm_call_id,
+                                "type": "function",
+                                "function": {
+                                    "name": "confirm_changes",
+                                    "arguments": "{}",
+                                },
+                            }
+                        )
+
+                        # Start the confirm_changes tool call
+                        confirm_start = ToolCallStartEvent(
+                            tool_call_id=confirm_call_id,
+                            tool_call_name="confirm_changes",
+                        )
+                        events.append(confirm_start)
+
+                        # Empty args for confirm_changes
+                        confirm_args = ToolCallArgsEvent(
+                            tool_call_id=confirm_call_id,
+                            delta="{}",
+                        )
+                        events.append(confirm_args)
+
+                        # End the confirm_changes tool call
+                        confirm_end = ToolCallEndEvent(
+                            tool_call_id=confirm_call_id,
+                        )
+                        events.append(confirm_end)
+
+                        # Emit MessagesSnapshotEvent so confirm_changes persists after RUN_FINISHED
+                        # Build assistant message with pending confirm_changes tool call
+                        assistant_message = {
+                            "id": generate_event_id(),
+                            "role": "assistant",
+                            "tool_calls": self.pending_tool_calls.copy(),  # Includes confirm_changes
+                        }
+
+                        # Build complete messages array: input messages + assistant message + any tool results
+                        all_messages = list(self.input_messages) + [assistant_message] + self.tool_results.copy()
+
+                        # Emit MessagesSnapshotEvent
+                        messages_snapshot_event = MessagesSnapshotEvent(
+                            type=EventType.MESSAGES_SNAPSHOT, messages=all_messages
+                        )
+                        logger.info(
+                            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")
+                    elif tool_was_predictive:
+                        logger.info("  >>> Skipping confirm_changes - require_confirmation is False")
+
+                    # Clear pending updates and reset tool name tracker
+                    self.pending_state_updates.clear()
+                    self.last_emitted_state.clear()
+                    self.current_tool_call_name = None  # Reset for next tool call
+
+            elif isinstance(content, FunctionApprovalRequestContent):
+                # Human in the loop - function approval request
+                logger.info("=== FUNCTION APPROVAL REQUEST ===")
+                logger.info(f"  Function: {content.function_call.name}")
+                logger.info(f"  Call ID: {content.function_call.call_id}")
+
+                # Parse the arguments to extract state for predictive UI updates
+                parsed_args = content.function_call.parse_arguments()
+                logger.info(f"  Parsed args keys: {list(parsed_args.keys()) if parsed_args else 'None'}")
+
+                # Check if this matches our predict_state_config and emit state
+                if parsed_args and self.predict_state_config:
+                    logger.info(f"  Checking predict_state_config: {self.predict_state_config}")
+                    for state_key, config in self.predict_state_config.items():
+                        if config["tool"] == content.function_call.name:
+                            tool_arg_name = config["tool_argument"]
+                            logger.info(
+                                f"  MATCHED tool '{content.function_call.name}' for state key '{state_key}', arg='{tool_arg_name}'"
+                            )
+
+                            # Extract the state value
+                            if tool_arg_name == "*":
+                                state_value = parsed_args
+                            elif tool_arg_name in parsed_args:
+                                state_value = parsed_args[tool_arg_name]
+                            else:
+                                logger.warning(f"  Tool argument '{tool_arg_name}' not found in parsed args")
+                                continue
+
+                            # Update current state
+                            self.current_state[state_key] = state_value
+                            logger.info(
+                                f"  >>> Emitting StateSnapshotEvent for key '{state_key}', value type: {type(state_value)}"
+                            )
+
+                            # Emit state snapshot
+                            state_snapshot = StateSnapshotEvent(
+                                snapshot=self.current_state,
+                            )
+                            events.append(state_snapshot)
+
+                # The tool call has been streamed already (Start/Args events)
+                # Now we need to close it with an End event before the agent waits for approval
+                if content.function_call.call_id:
+                    end_event = ToolCallEndEvent(
+                        tool_call_id=content.function_call.call_id,
+                    )
+                    logger.info(
+                        f"  >>> Emitting ToolCallEndEvent for approval-required tool '{content.function_call.call_id}'"
+                    )
+                    events.append(end_event)
+
+                # Emit custom event for approval request
+                # Note: In AG-UI protocol, the frontend handles interrupts automatically
+                # when it sees a tool call with the configured name (via predict_state_config)
+                # This custom event is for additional metadata if needed
+                approval_event = CustomEvent(
+                    name="function_approval_request",
+                    value={
+                        "id": content.id,
+                        "function_call": {
+                            "call_id": content.function_call.call_id,
+                            "name": content.function_call.name,
+                            "arguments": content.function_call.parse_arguments(),
+                        },
+                    },
+                )
+                logger.info(f"  >>> Emitting function_approval_request custom event for '{content.function_call.name}'")
+                events.append(approval_event)
+
+        return events
+
+    def create_run_started_event(self) -> RunStartedEvent:
+        """Create a run started event."""
+        return RunStartedEvent(
+            run_id=self.run_id,
+            thread_id=self.thread_id,
+        )
+
+    def create_run_finished_event(self, result: Any = None) -> RunFinishedEvent:
+        """Create a run finished event."""
+        return RunFinishedEvent(
+            run_id=self.run_id,
+            thread_id=self.thread_id,
+            result=result,
+        )
+
+    def create_message_start_event(self, message_id: str, role: str = "assistant") -> TextMessageStartEvent:
+        """Create a message start event."""
+        return TextMessageStartEvent(
+            message_id=message_id,
+            role=role,  # type: ignore
+        )
+
+    def create_message_end_event(self, message_id: str) -> TextMessageEndEvent:
+        """Create a message end event."""
+        return TextMessageEndEvent(
+            message_id=message_id,
+        )
+
+    def create_state_snapshot_event(self, state: dict[str, Any]) -> StateSnapshotEvent:
+        """Create a state snapshot event.
+
+        Args:
+            state: The complete state snapshot.
+
+        Returns:
+            StateSnapshotEvent.
+        """
+        return StateSnapshotEvent(
+            snapshot=state,
+        )
+
+    def create_state_delta_event(self, delta: list[dict[str, Any]]) -> StateDeltaEvent:
+        """Create a state delta event using JSON Patch format (RFC 6902).
+
+        Args:
+            delta: List of JSON Patch operations.
+
+        Returns:
+            StateDeltaEvent.
+        """
+        return StateDeltaEvent(
+            delta=delta,
+        )

python/packages/ag-ui/agent_framework_ag_ui/_message_adapters.py

@@ -0,0 +1,218 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Message format conversion between AG-UI and Agent Framework."""
+
+from typing import Any
+
+from agent_framework import (
+    ChatMessage,
+    FunctionApprovalResponseContent,
+    FunctionCallContent,
+    Role,
+    TextContent,
+)
+
+# Role mapping constants
+_AGUI_TO_FRAMEWORK_ROLE = {
+    "user": Role.USER,
+    "assistant": Role.ASSISTANT,
+    "system": Role.SYSTEM,
+}
+
+_FRAMEWORK_TO_AGUI_ROLE = {
+    Role.USER: "user",
+    Role.ASSISTANT: "assistant",
+    Role.SYSTEM: "system",
+}
+
+
+def agui_messages_to_agent_framework(messages: list[dict[str, Any]]) -> list[ChatMessage]:
+    """Convert AG-UI messages to Agent Framework format.
+
+    Args:
+        messages: List of AG-UI messages
+
+    Returns:
+        List of Agent Framework ChatMessage objects
+    """
+    result: list[ChatMessage] = []
+    for msg in messages:
+        # Check for backend tool rendering results FIRST (may not have role field)
+        if "actionExecutionId" in msg or "actionName" in msg:
+            # Backend tool rendering - convert to FunctionResultContent
+            from agent_framework import FunctionResultContent
+
+            tool_call_id = msg.get("actionExecutionId", "")
+            result_content = msg.get("result", msg.get("content", ""))
+
+            chat_msg = ChatMessage(
+                role=Role.ASSISTANT,  # Tool results are assistant messages
+                contents=[FunctionResultContent(call_id=tool_call_id, result=result_content)],
+            )
+
+            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")
+        if role_str == "tool":
+            # Check if this is a standard tool result (has tool_call_id or toolCallId)
+            tool_call_id = msg.get("tool_call_id") or msg.get("toolCallId")
+            result_content = msg.get("content", "")
+
+            # Distinguish between backend tool results and approval responses
+            # Approval responses have {"accepted": ...} structure
+            is_approval = False
+            if result_content:
+                import json
+
+                try:
+                    parsed_content = json.loads(result_content)
+                    is_approval = "accepted" in parsed_content
+                except (json.JSONDecodeError, TypeError):
+                    is_approval = False
+
+            # 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
+                from agent_framework import FunctionResultContent
+
+                chat_msg = ChatMessage(
+                    role=Role.ASSISTANT,  # Tool results are assistant messages
+                    contents=[FunctionResultContent(call_id=tool_call_id, result=result_content)],
+                )
+
+                if "id" in msg:
+                    chat_msg.message_id = msg["id"]
+
+                result.append(chat_msg)
+                continue
+            else:
+                # Human-in-the-loop approval response - mark for special handling
+                content = msg.get("content", "")
+                chat_msg = ChatMessage(
+                    role=Role.USER,  # Approval responses are user messages
+                    contents=[TextContent(text=content)],
+                )
+                # 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"]
+
+                result.append(chat_msg)
+                continue
+
+        role = _AGUI_TO_FRAMEWORK_ROLE.get(role_str, Role.USER)
+
+        # Check if this message contains function approvals
+        if "function_approvals" in msg and msg["function_approvals"]:
+            # Convert function approvals to FunctionApprovalResponseContent
+            contents: list[Any] = []
+            for approval in msg["function_approvals"]:
+                # Create FunctionCallContent with the modified arguments
+                func_call = FunctionCallContent(
+                    call_id=approval.get("call_id", ""),
+                    name=approval.get("name", ""),
+                    arguments=approval.get("arguments", {}),
+                )
+
+                # Create the approval response
+                approval_response = FunctionApprovalResponseContent(
+                    approved=approval.get("approved", True),
+                    id=approval.get("id", ""),
+                    function_call=func_call,
+                )
+                contents.append(approval_response)
+
+            chat_msg = ChatMessage(role=role, contents=contents)  # type: ignore[arg-type]
+        else:
+            # Regular text message
+            content = msg.get("content", "")
+            if isinstance(content, str):
+                chat_msg = ChatMessage(role=role, contents=[TextContent(text=content)])
+            else:
+                chat_msg = ChatMessage(role=role, contents=[TextContent(text=str(content))])
+
+        if "id" in msg:
+            chat_msg.message_id = msg["id"]
+
+        result.append(chat_msg)
+
+    return result
+
+
+def agent_framework_messages_to_agui(messages: list[ChatMessage]) -> list[dict[str, Any]]:
+    """Convert Agent Framework messages to AG-UI format.
+
+    Args:
+        messages: List of Agent Framework ChatMessage objects
+
+    Returns:
+        List of AG-UI message dictionaries
+    """
+    result: list[dict[str, Any]] = []
+    for msg in messages:
+        role = _FRAMEWORK_TO_AGUI_ROLE.get(msg.role, "user")
+
+        content_text = ""
+        tool_calls: list[dict[str, Any]] = []
+
+        for content in msg.contents:
+            if isinstance(content, TextContent):
+                content_text += content.text
+            elif isinstance(content, FunctionCallContent):
+                tool_calls.append(
+                    {
+                        "id": content.call_id,
+                        "type": "function",
+                        "function": {
+                            "name": content.name,
+                            "arguments": content.arguments,
+                        },
+                    }
+                )
+
+        agui_msg: dict[str, Any] = {
+            "role": role,
+            "content": content_text,
+        }
+
+        if msg.message_id:
+            agui_msg["id"] = msg.message_id
+
+        if tool_calls:
+            agui_msg["tool_calls"] = tool_calls
+
+        result.append(agui_msg)
+
+    return result
+
+
+def extract_text_from_contents(contents: list[Any]) -> str:
+    """Extract text from Agent Framework contents.
+
+    Args:
+        contents: List of content objects
+
+    Returns:
+        Concatenated text
+    """
+    text_parts: list[str] = []
+    for content in contents:
+        if isinstance(content, TextContent):
+            text_parts.append(content.text)
+        elif hasattr(content, "text"):
+            text_parts.append(content.text)
+    return "".join(text_parts)
+
+
+__all__ = [
+    "agui_messages_to_agent_framework",
+    "agent_framework_messages_to_agui",
+    "extract_text_from_contents",
+]

python/packages/ag-ui/agent_framework_ag_ui/_orchestrators.py

@@ -0,0 +1,439 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Orchestrators for multi-turn agent flows."""
+
+import json
+import logging
+import uuid
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from typing import TYPE_CHECKING, Any
+
+from ag_ui.core import (
+    BaseEvent,
+    RunErrorEvent,
+    TextMessageContentEvent,
+    TextMessageEndEvent,
+    TextMessageStartEvent,
+)
+from agent_framework import AgentProtocol, AgentThread, TextContent
+
+from ._utils import generate_event_id
+
+if TYPE_CHECKING:
+    from ._agent import AgentConfig
+    from ._confirmation_strategies import ConfirmationStrategy
+
+
+logger = logging.getLogger(__name__)
+
+
+class ExecutionContext:
+    """Shared context for orchestrators."""
+
+    def __init__(
+        self,
+        input_data: dict[str, Any],
+        agent: AgentProtocol,
+        config: "AgentConfig",  # noqa: F821
+        confirmation_strategy: "ConfirmationStrategy | None" = None,  # noqa: F821
+    ):
+        """Initialize execution context.
+
+        Args:
+            input_data: AG-UI run input containing messages, state, etc.
+            agent: The Agent Framework agent to execute
+            config: Agent configuration
+            confirmation_strategy: Strategy for generating confirmation messages
+        """
+        self.input_data = input_data
+        self.agent = agent
+        self.config = config
+        self.confirmation_strategy = confirmation_strategy
+
+        # Lazy-loaded properties
+        self._messages = None
+        self._last_message = None
+        self._run_id: str | None = None
+        self._thread_id: str | None = None
+
+    @property
+    def messages(self):
+        """Get converted Agent Framework messages (lazy loaded)."""
+        if self._messages is None:
+            from ._message_adapters import agui_messages_to_agent_framework
+
+            raw = self.input_data.get("messages", [])
+            self._messages = agui_messages_to_agent_framework(raw)
+        return self._messages
+
+    @property
+    def last_message(self):
+        """Get the last message in the conversation (lazy loaded)."""
+        if self._last_message is None and self.messages:
+            self._last_message = self.messages[-1]
+        return self._last_message
+
+    @property
+    def run_id(self) -> str:
+        """Get or generate run ID."""
+        if self._run_id is None:
+            self._run_id = self.input_data.get("run_id") or str(uuid.uuid4())
+        # This should never be None after the if block above, but satisfy type checkers
+        if self._run_id is None:  # pragma: no cover
+            raise RuntimeError("Failed to initialize run_id")
+        return self._run_id
+
+    @property
+    def thread_id(self) -> str:
+        """Get or generate thread ID."""
+        if self._thread_id is None:
+            self._thread_id = self.input_data.get("thread_id") or str(uuid.uuid4())
+        # This should never be None after the if block above, but satisfy type checkers
+        if self._thread_id is None:  # pragma: no cover
+            raise RuntimeError("Failed to initialize thread_id")
+        return self._thread_id
+
+
+class Orchestrator(ABC):
+    """Base orchestrator for agent execution flows."""
+
+    @abstractmethod
+    def can_handle(self, context: ExecutionContext) -> bool:
+        """Determine if this orchestrator handles the current request.
+
+        Args:
+            context: Execution context with input data and agent
+
+        Returns:
+            True if this orchestrator should handle the request
+        """
+        ...
+
+    @abstractmethod
+    async def run(
+        self,
+        context: ExecutionContext,
+    ) -> AsyncGenerator[BaseEvent, None]:
+        """Execute the orchestration and yield events.
+
+        Args:
+            context: Execution context
+
+        Yields:
+            AG-UI events
+        """
+        # This is never executed - just satisfies mypy's requirement for async generators
+        if False:  # pragma: no cover
+            yield
+        raise NotImplementedError
+
+
+class HumanInTheLoopOrchestrator(Orchestrator):
+    """Handles tool approval responses from user."""
+
+    def can_handle(self, context: ExecutionContext) -> bool:
+        """Check if last message is a tool approval response.
+
+        Args:
+            context: Execution context
+
+        Returns:
+            True if last message is a tool result
+        """
+        msg = context.last_message
+        if not msg or not hasattr(msg, "metadata"):
+            return False
+
+        metadata = getattr(msg, "metadata", None)
+        if not metadata:
+            return False
+
+        return bool(metadata.get("is_tool_result", False))
+
+    async def run(
+        self,
+        context: ExecutionContext,
+    ) -> AsyncGenerator[BaseEvent, None]:
+        """Process approval response and generate confirmation events.
+
+        This implementation is extracted from the legacy _agent.py lines 144-244.
+
+        Args:
+            context: Execution context
+
+        Yields:
+            AG-UI events (TextMessage, RunFinished)
+        """
+        from ._confirmation_strategies import DefaultConfirmationStrategy
+        from ._events import AgentFrameworkEventBridge
+
+        logger.info("=== TOOL RESULT DETECTED (HumanInTheLoopOrchestrator) ===")
+
+        # Create event bridge for run events
+        event_bridge = AgentFrameworkEventBridge(
+            run_id=context.run_id,
+            thread_id=context.thread_id,
+        )
+
+        # CRITICAL: Every AG-UI run must start with RunStartedEvent
+        yield event_bridge.create_run_started_event()
+
+        # Get confirmation strategy (use default if none provided)
+        strategy = context.confirmation_strategy
+        if strategy is None:
+            strategy = DefaultConfirmationStrategy()
+
+        # Parse the tool result content
+        tool_content_text = ""
+        last_message = context.last_message
+        if last_message:
+            for content in last_message.contents:
+                if isinstance(content, TextContent):
+                    tool_content_text = content.text
+                    break
+
+        try:
+            tool_result = json.loads(tool_content_text)
+            accepted = tool_result.get("accepted", False)
+            steps = tool_result.get("steps", [])
+
+            logger.info(f"  Accepted: {accepted}")
+            logger.info(f"  Steps count: {len(steps)}")
+
+            # Emit a text message confirming execution
+            message_id = generate_event_id()
+
+            yield TextMessageStartEvent(message_id=message_id, role="assistant")
+
+            # Check if this is confirm_changes (no steps) or function approval (has steps)
+            if not steps:
+                # This is confirm_changes for predictive state updates
+                if accepted:
+                    confirmation_message = strategy.on_state_confirmed()
+                else:
+                    confirmation_message = strategy.on_state_rejected()
+            elif accepted:
+                # User approved - execute the enabled steps (function approval flow)
+                confirmation_message = strategy.on_approval_accepted(steps)
+            else:
+                # User rejected
+                confirmation_message = strategy.on_approval_rejected(steps)
+
+            yield TextMessageContentEvent(
+                message_id=message_id,
+                delta=confirmation_message,
+            )
+
+            yield TextMessageEndEvent(message_id=message_id)
+
+            # Emit run finished
+            yield event_bridge.create_run_finished_event()
+
+        except json.JSONDecodeError:
+            logger.error(f"Failed to parse tool result: {tool_content_text}")
+            yield RunErrorEvent(message=f"Invalid tool result format: {tool_content_text[:100]}")
+            yield event_bridge.create_run_finished_event()
+
+
+class DefaultOrchestrator(Orchestrator):
+    """Standard agent execution (no special handling)."""
+
+    def can_handle(self, context: ExecutionContext) -> bool:
+        """Always returns True as this is the fallback orchestrator.
+
+        Args:
+            context: Execution context
+
+        Returns:
+            Always True
+        """
+        return True
+
+    async def run(
+        self,
+        context: ExecutionContext,
+    ) -> AsyncGenerator[BaseEvent, None]:
+        """Standard agent run with event translation.
+
+        This implements the default agent execution flow using the event bridge
+        to translate Agent Framework events to AG-UI events.
+
+        Args:
+            context: Execution context
+
+        Yields:
+            AG-UI events
+        """
+        from ._events import AgentFrameworkEventBridge
+
+        logger.info(f"Starting default agent run for thread_id={context.thread_id}, run_id={context.run_id}")
+
+        # Initialize state tracking
+        initial_state = context.input_data.get("state", {})
+        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
+        skip_text_content = response_format is not None
+
+        # Create event bridge
+        event_bridge = AgentFrameworkEventBridge(
+            run_id=context.run_id,
+            thread_id=context.thread_id,
+            predict_state_config=context.config.predict_state_config,
+            current_state=current_state,
+            skip_text_content=skip_text_content,
+            input_messages=context.input_data.get("messages", []),
+            require_confirmation=context.config.require_confirmation,
+        )
+
+        yield event_bridge.create_run_started_event()
+
+        # Emit PredictState custom event if we have predictive state config
+        if context.config.predict_state_config:
+            from ag_ui.core import CustomEvent, EventType
+
+            predict_state_value = [
+                {
+                    "state_key": state_key,
+                    "tool": config["tool"],
+                    "tool_argument": config["tool_argument"],
+                }
+                for state_key, config in context.config.predict_state_config.items()
+            ]
+
+            yield CustomEvent(
+                type=EventType.CUSTOM,
+                name="PredictState",
+                value=predict_state_value,
+            )
+
+        # If we have a state schema, ensure we emit initial state snapshot
+        if context.config.state_schema:
+            # Initialize missing state fields with appropriate empty values based on schema type
+            for key, schema in context.config.state_schema.items():
+                if key not in current_state:
+                    # Default to empty object; use empty array if schema specifies "array" type
+                    current_state[key] = [] if isinstance(schema, dict) and schema.get("type") == "array" else {}  # type: ignore
+            yield event_bridge.create_state_snapshot_event(current_state)
+
+        # Create thread for context tracking
+        thread = AgentThread()
+        thread.metadata = {  # type: ignore[attr-defined]
+            "ag_ui_thread_id": context.thread_id,
+            "ag_ui_run_id": context.run_id,
+        }
+
+        # Inject current state into thread metadata so agent can access it
+        if current_state:
+            thread.metadata["current_state"] = current_state  # type: ignore[attr-defined]
+
+        # Add incoming AG-UI messages to the thread history
+        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:
+            logger.warning("No messages provided in AG-UI input")
+            yield event_bridge.create_run_finished_event()
+            return
+
+        # Inject current state as system message context if we have state
+        messages_to_run: list[Any] = []
+        if current_state and context.config.state_schema:
+            state_json = json.dumps(current_state, indent=2)
+            from agent_framework import ChatMessage
+
+            state_context_msg = ChatMessage(
+                role="system",
+                contents=[
+                    TextContent(
+                        text=f"""Current state of the application:
+{state_json}
+
+When modifying state, you MUST include ALL existing data plus your changes.
+For example, if adding a new ingredient, include all existing ingredients PLUS the new one.
+Never replace existing data - always append or merge."""
+                    )
+                ],
+            )
+            messages_to_run.append(state_context_msg)
+
+        messages_to_run.append(new_message)
+
+        # 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):
+            all_updates.append(update)
+            events = await event_bridge.from_agent_run_update(update)
+            for event in events:
+                yield event
+
+        # 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")
+            yield event_bridge.create_run_finished_event()
+            return
+
+        # After streaming completes, check if agent has response_format and extract structured output
+        if all_updates and response_format:
+            from agent_framework import AgentRunResponse
+            from pydantic import BaseModel
+
+            logger.info(f"Processing structured output, update count: {len(all_updates)}")
+
+            # Convert streaming updates to final response to get the structured output
+            final_response = AgentRunResponse.from_agent_run_response_updates(
+                all_updates, output_format_type=response_format
+            )
+
+            if final_response.value and isinstance(final_response.value, BaseModel):
+                # Convert Pydantic model to dict
+                response_dict = final_response.value.model_dump(mode="json", exclude_none=True)
+                logger.info(f"Received structured output: {list(response_dict.keys())}")
+
+                # Extract state fields based on state_schema
+                state_updates: dict[str, Any] = {}
+
+                if context.config.state_schema:
+                    # Use state_schema to determine which fields are state
+                    for state_key in context.config.state_schema.keys():
+                        if state_key in response_dict:
+                            state_updates[state_key] = response_dict[state_key]
+                else:
+                    # No schema: treat all non-message fields as state
+                    state_updates = {k: v for k, v in response_dict.items() if k != "message"}
+
+                # Apply state updates if any found
+                if state_updates:
+                    current_state.update(state_updates)
+
+                    # Emit StateSnapshotEvent with the updated state
+                    state_snapshot = event_bridge.create_state_snapshot_event(current_state)
+                    yield state_snapshot
+                    logger.info(f"Emitted StateSnapshotEvent with updates: {list(state_updates.keys())}")
+
+                # If there's a message field, emit it as chat text
+                if "message" in response_dict and response_dict["message"]:
+                    message_id = generate_event_id()
+                    yield TextMessageStartEvent(message_id=message_id, role="assistant")
+                    yield TextMessageContentEvent(message_id=message_id, delta=response_dict["message"])
+                    yield TextMessageEndEvent(message_id=message_id)
+                    logger.info(f"Emitted conversational message: {response_dict['message'][:100]}...")
+
+        if event_bridge.current_message_id:
+            yield event_bridge.create_message_end_event(event_bridge.current_message_id)
+
+        yield event_bridge.create_run_finished_event()
+        logger.info(f"Completed agent run for thread_id={context.thread_id}, run_id={context.run_id}")
+
+
+__all__ = [
+    "Orchestrator",
+    "ExecutionContext",
+    "HumanInTheLoopOrchestrator",
+    "DefaultOrchestrator",
+]

python/packages/ag-ui/agent_framework_ag_ui/_types.py

@@ -0,0 +1,27 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Type definitions for AG-UI integration."""
+
+from typing import Any, TypedDict
+
+
+class PredictStateConfig(TypedDict):
+    """Configuration for predictive state updates."""
+
+    state_key: str
+    tool: str
+    tool_argument: str | None
+
+
+class RunMetadata(TypedDict):
+    """Metadata for agent run."""
+
+    run_id: str
+    thread_id: str
+    predict_state: list[PredictStateConfig] | None
+
+
+class AgentState(TypedDict):
+    """Base state for AG-UI agents."""
+
+    messages: list[Any] | None

python/packages/ag-ui/agent_framework_ag_ui/_utils.py

@@ -0,0 +1,57 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Utility functions for AG-UI integration."""
+
+import copy
+import uuid
+from dataclasses import asdict, is_dataclass
+from datetime import date, datetime
+from typing import Any
+
+
+def generate_event_id() -> str:
+    """Generate a unique event ID."""
+    return str(uuid.uuid4())
+
+
+def merge_state(current: dict[str, Any], update: dict[str, Any]) -> dict[str, Any]:
+    """Merge state updates.
+
+    Args:
+        current: Current state dictionary
+        update: Update to apply
+
+    Returns:
+        Merged state
+    """
+    result = copy.deepcopy(current)
+    result.update(update)
+    return result
+
+
+def make_json_safe(obj: Any) -> Any:  # noqa: ANN401
+    """Make an object JSON serializable.
+
+    Args:
+        obj: Object to make JSON safe
+
+    Returns:
+        JSON-serializable version of the object
+    """
+    if obj is None or isinstance(obj, (str, int, float, bool)):
+        return obj
+    if isinstance(obj, (datetime, date)):
+        return obj.isoformat()
+    if is_dataclass(obj):
+        return asdict(obj)  # type: ignore[arg-type]
+    if hasattr(obj, "model_dump"):
+        return obj.model_dump()  # type: ignore[no-any-return]
+    if hasattr(obj, "dict"):
+        return obj.dict()  # type: ignore[no-any-return]
+    if hasattr(obj, "__dict__"):
+        return {key: make_json_safe(value) for key, value in vars(obj).items()}  # type: ignore[misc]
+    if isinstance(obj, (list, tuple)):
+        return [make_json_safe(item) for item in obj]  # type: ignore[misc]
+    if isinstance(obj, dict):
+        return {key: make_json_safe(value) for key, value in obj.items()}  # type: ignore[misc]
+    return str(obj)

python/packages/ag-ui/agent_framework_ag_ui/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

python/packages/ag-ui/examples/.env.example

@@ -0,0 +1,3 @@
+AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
+AZURE_OPENAI_API_KEY=your-api-key-here
+PORT=8000

python/packages/ag-ui/examples/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "python.analysis.extraPaths": [
+        "${workspaceFolder}/packages/ag-ui/examples"
+    ]
+}

python/packages/ag-ui/examples/README.md

@@ -0,0 +1,243 @@
+# Agent Framework AG-UI Integration
+
+AG-UI protocol integration for Agent Framework, enabling seamless integration with AG-UI's web interface and streaming protocol.
+
+## Installation
+
+```bash
+pip install agent-framework-ag-ui
+```
+
+## Quick Start
+
+```python
+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
+
+# Create your agent
+agent = ChatAgent(
+    name="my_agent",
+    instructions="You are a helpful assistant.",
+    chat_client=AzureOpenAIChatClient(model_id="gpt-4o"),
+)
+
+# Create FastAPI app and add AG-UI endpoint
+app = FastAPI()
+add_agent_framework_fastapi_endpoint(app, agent, "/agent")
+
+# Run with: uvicorn main:app --reload
+```
+
+## Features
+
+This integration supports all 7 AG-UI features:
+
+1. **Agentic Chat**: Basic streaming chat with tool calling support
+2. **Backend Tool Rendering**: Tools executed on backend with results streamed via ToolCallResultEvent
+3. **Human in the Loop**: Function approval requests for user confirmation before tool execution
+4. **Agentic Generative UI**: Async tools for long-running operations with progress updates
+5. **Tool-based Generative UI**: Custom UI components rendered on frontend based on tool calls
+6. **Shared State**: Bidirectional state sync using StateSnapshotEvent and StateDeltaEvent
+7. **Predictive State Updates**: Stream tool arguments as optimistic state updates during execution
+
+## Examples
+
+Complete examples for all features are in the `examples/` directory:
+
+- `examples/agents/simple_agent.py` - Basic agentic chat
+- `examples/agents/weather_agent.py` - Backend tool rendering
+- `examples/agents/task_planner_agent.py` - Human in the loop with approvals
+- `examples/agents/research_assistant_agent.py` - Agentic generative UI
+- `examples/agents/ui_generator_agent.py` - Tool-based generative UI
+- `examples/agents/recipe_agent.py` - Shared state management
+- `examples/agents/document_writer_agent.py` - Predictive state updates
+- `examples/server/main.py` - FastAPI server with all endpoints
+
+Run the example server:
+
+```bash
+cd examples/server
+uvicorn main:app --reload
+```
+
+To enable debug logging:
+
+```bash
+ENABLE_DEBUG_LOGGING=1 uvicorn main:app --reload
+```
+
+The server exposes endpoints at:
+- `/agentic_chat`
+- `/backend_tool_rendering`
+- `/human_in_the_loop`
+- `/agentic_generative_ui`
+- `/tool_based_generative_ui`
+- `/shared_state`
+- `/predictive_state_updates`
+
+## Architecture
+
+The package uses a clean, orchestrator-based architecture:
+
+- **AgentFrameworkAgent**: Lightweight wrapper that delegates to orchestrators
+- **Orchestrators**: Handle different execution flows (default, human-in-the-loop, etc.)
+- **Confirmation Strategies**: Domain-specific confirmation messages (extensible)
+- **AgentFrameworkEventBridge**: Converts AgentRunResponseUpdate to AG-UI events
+- **Message Adapters**: Bidirectional conversion between AG-UI and Agent Framework message formats
+- **FastAPI Endpoint**: Streaming HTTP endpoint with Server-Sent Events (SSE)
+
+### Key Design Patterns
+
+- **Orchestrator Pattern**: Separates flow control from protocol translation
+- **Strategy Pattern**: Pluggable confirmation message strategies
+- **Context Object**: Lazy-loaded execution context passed to orchestrators
+- **Event Bridge**: Stateless translation of Agent Framework events to AG-UI events
+
+## Advanced Usage
+
+### Shared State
+
+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
+
+# Create your agent
+agent = ChatAgent(
+    name="recipe_agent",
+    chat_client=AzureOpenAIChatClient(model_id="gpt-4o"),
+)
+
+state_schema = {
+    "recipe": {
+        "type": "object",
+        "properties": {
+            "name": {"type": "string"},
+            "ingredients": {"type": "array"}
+        }
+    }
+}
+
+# Configure which tool updates which state fields
+predict_state_config = {
+    "recipe": {"tool": "update_recipe", "tool_argument": "recipe_data"}
+}
+
+wrapped_agent = AgentFrameworkAgent(
+    agent=agent,
+    state_schema=state_schema,
+    predict_state_config=predict_state_config,
+)
+```
+
+### Predictive State Updates
+
+Predictive state updates automatically stream tool arguments as optimistic state updates:
+
+```python
+from agent_framework import ChatAgent
+from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework_ag_ui import AgentFrameworkAgent
+
+# Create your agent
+agent = ChatAgent(
+    name="document_writer",
+    chat_client=AzureOpenAIChatClient(model_id="gpt-4o"),
+)
+
+predict_state_config = {
+    "current_title": {"tool": "write_document", "tool_argument": "title"},
+    "current_content": {"tool": "write_document", "tool_argument": "content"},
+}
+
+wrapped_agent = AgentFrameworkAgent(
+    agent=agent,
+    state_schema={"current_title": {"type": "string"}, "current_content": {"type": "string"}},
+    predict_state_config=predict_state_config,
+    require_confirmation=True,  # User can approve/reject changes
+)
+```
+
+### Custom Confirmation Strategies
+
+Provide domain-specific confirmation messages:
+
+```python
+from typing import Any
+from agent_framework import ChatAgent
+from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework_ag_ui import AgentFrameworkAgent, ConfirmationStrategy
+
+class CustomConfirmationStrategy(ConfirmationStrategy):
+    def on_approval_accepted(self, steps: list[dict[str, Any]]) -> str:
+        return "Your custom approval message!"
+    
+    def on_approval_rejected(self, steps: list[dict[str, Any]]) -> str:
+        return "Your custom rejection message!"
+    
+    def on_state_confirmed(self) -> str:
+        return "State changes confirmed!"
+    
+    def on_state_rejected(self) -> str:
+        return "State changes rejected!"
+
+agent = ChatAgent(
+    name="custom_agent",
+    chat_client=AzureOpenAIChatClient(model_id="gpt-4o"),
+)
+
+wrapped_agent = AgentFrameworkAgent(
+    agent=agent,
+    confirmation_strategy=CustomConfirmationStrategy(),
+)
+```
+
+### Human in the Loop
+
+Human-in-the-loop is automatically handled when tools are marked for approval:
+
+```python
+from agent_framework import ai_function
+
+@ai_function(approval_mode="always_require")
+def sensitive_action(param: str) -> str:
+    """This action requires user approval."""
+    return f"Executed with {param}"
+
+# The orchestrator automatically detects approval responses and handles them
+```
+
+### Custom Orchestrators
+
+Add custom execution flows by implementing the Orchestrator pattern:
+
+```python
+from agent_framework_ag_ui._orchestrators import Orchestrator, ExecutionContext
+
+class MyCustomOrchestrator(Orchestrator):
+    def can_handle(self, context: ExecutionContext) -> bool:
+        # Return True if this orchestrator should handle the request
+        return context.input_data.get("custom_mode") == True
+    
+    async def run(self, context: ExecutionContext):
+        # Custom execution logic
+        yield RunStartedEvent(...)
+        # ... your custom flow
+        yield RunFinishedEvent(...)
+
+wrapped_agent = AgentFrameworkAgent(
+    agent=your_agent,
+    orchestrators=[MyCustomOrchestrator(), DefaultOrchestrator()],
+)
+
+## Documentation
+
+For detailed documentation, see [DESIGN.md](DESIGN.md).
+
+## License
+
+MIT

python/packages/ag-ui/examples/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) Microsoft. All rights reserved.

python/packages/ag-ui/examples/__main__.py

@@ -0,0 +1,8 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Entry point for running the AG-UI examples server as a module."""
+
+from .server.main import main
+
+if __name__ == "__main__":
+    main()

python/packages/ag-ui/examples/agents/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Example agents for AG-UI demonstration."""

python/packages/ag-ui/examples/agents/document_writer_agent.py

@@ -0,0 +1,58 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Example agent demonstrating predictive state updates with document writing."""
+
+from agent_framework import ChatAgent, ai_function
+from agent_framework.azure import AzureOpenAIChatClient
+
+from agent_framework_ag_ui import AgentFrameworkAgent, DocumentWriterConfirmationStrategy
+
+
+@ai_function
+def write_document_local(document: str) -> str:
+    """Write a document. Use markdown formatting to format the document.
+
+    It's good to format the document extensively so it's easy to read.
+    You can use all kinds of markdown.
+    However, do not use italic or strike-through formatting, it's reserved for another purpose.
+    You MUST write the full document, even when changing only a few words.
+    When making edits to the document, try to make them minimal - do not change every word.
+    Keep stories SHORT!
+
+    Args:
+        document: The complete document content in markdown format
+
+    Returns:
+        Confirmation that the document was written
+    """
+    return "Document written."
+
+
+agent = ChatAgent(
+    name="document_writer",
+    instructions=(
+        "You are a helpful assistant for writing documents. "
+        "To write the document, you MUST use the write_document_local tool. "
+        "You MUST write the full document, even when changing only a few words. "
+        "When you wrote the document, DO NOT repeat it as a message. "
+        "Just briefly summarize the changes you made. 2 sentences max. "
+        "\n\n"
+        "The current state of the document will be provided to you. "
+        "When editing, make minimal changes - do not change every word unless requested."
+    ),
+    chat_client=AzureOpenAIChatClient(),
+    tools=[write_document_local],
+)
+
+document_writer_agent = AgentFrameworkAgent(
+    agent=agent,
+    name="DocumentWriter",
+    description="Writes and edits documents with predictive state updates",
+    state_schema={
+        "document": {"type": "string", "description": "The current document content"},
+    },
+    predict_state_config={
+        "document": {"tool": "write_document_local", "tool_argument": "document"},
+    },
+    confirmation_strategy=DocumentWriterConfirmationStrategy(),
+)

python/packages/ag-ui/examples/agents/human_in_the_loop_agent.py

@@ -0,0 +1,76 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Human-in-the-loop agent demonstrating step customization (Feature 5)."""
+
+from enum import Enum
+
+from agent_framework import ChatAgent, ai_function
+from agent_framework.azure import AzureOpenAIChatClient
+from pydantic import BaseModel, Field
+
+
+class StepStatus(str, Enum):
+    """Status of a task step."""
+
+    ENABLED = "enabled"
+    DISABLED = "disabled"
+
+
+class TaskStep(BaseModel):
+    """A single step in a task execution plan."""
+
+    description: str = Field(..., description="The text of the step in imperative form (e.g., 'Dig hole', 'Open door')")
+    status: StepStatus = Field(default=StepStatus.ENABLED, description="Whether the step is enabled or disabled")
+
+
+@ai_function(
+    name="generate_task_steps",
+    description="Generate execution steps for a task",
+    approval_mode="always_require",
+)
+def generate_task_steps(steps: list[TaskStep]) -> str:
+    """Make up 10 steps (only a couple of words per step) that are required for a task.
+
+    The step should be in imperative form (i.e. Dig hole, Open door, ...).
+    Each step will have status='enabled' by default.
+
+    Args:
+        steps: An array of 10 step objects, each containing description and status
+
+    Returns:
+        Confirmation message
+    """
+    return f"Generated {len(steps)} execution steps for the task."
+
+
+# Create the human-in-the-loop agent using tool-based approach for predictive state
+human_in_the_loop_agent = ChatAgent(
+    name="human_in_the_loop_agent",
+    instructions="""You are a helpful assistant that can perform any task by breaking it down into steps.
+
+    When asked to perform a task, you MUST call the `generate_task_steps` function with the proper
+    number of steps per the request.
+
+    Rules for steps:
+    - Each step description should be in imperative form (e.g., "Dig hole", "Open door", "Prepare ingredients")
+    - Each step should be brief (only a couple of words)
+    - All steps must have status='enabled' initially
+
+    Example steps for "Build a robot":
+    1. "Design blueprint"
+    2. "Gather components"
+    3. "Assemble frame"
+    4. "Install motors"
+    5. "Wire electronics"
+    6. "Program controller"
+    7. "Test movements"
+    8. "Add sensors"
+    9. "Calibrate systems"
+    10. "Final testing"
+
+    After calling the function, provide a brief acknowledgment like:
+    "I've created a plan with 10 steps. You can customize which steps to enable before I proceed."
+    """,
+    chat_client=AzureOpenAIChatClient(),
+    tools=[generate_task_steps],
+)

python/packages/ag-ui/examples/agents/recipe_agent.py

@@ -0,0 +1,122 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Recipe agent example demonstrating shared state management (Feature 3)."""
+
+from enum import Enum
+
+from agent_framework import ChatAgent, ai_function
+from agent_framework.azure import AzureOpenAIChatClient
+from pydantic import BaseModel, Field
+
+from agent_framework_ag_ui import AgentFrameworkAgent, RecipeConfirmationStrategy
+
+
+class SkillLevel(str, Enum):
+    """The skill level required for the recipe."""
+
+    BEGINNER = "Beginner"
+    INTERMEDIATE = "Intermediate"
+    ADVANCED = "Advanced"
+
+
+class CookingTime(str, Enum):
+    """The cooking time of the recipe."""
+
+    FIVE_MIN = "5 min"
+    FIFTEEN_MIN = "15 min"
+    THIRTY_MIN = "30 min"
+    FORTY_FIVE_MIN = "45 min"
+    SIXTY_PLUS_MIN = "60+ min"
+
+
+class Ingredient(BaseModel):
+    """An ingredient with its details."""
+
+    icon: str = Field(..., description="Emoji icon representing the ingredient (e.g., 🥕)")
+    name: str = Field(..., description="Name of the ingredient")
+    amount: str = Field(..., description="Amount or quantity of the ingredient")
+
+
+class Recipe(BaseModel):
+    """A complete recipe."""
+
+    title: str = Field(..., description="The title of the recipe")
+    skill_level: SkillLevel = Field(..., description="The skill level required")
+    special_preferences: list[str] = Field(
+        default_factory=list, description="Dietary preferences (e.g., Vegetarian, Gluten-free)"
+    )
+    cooking_time: CookingTime = Field(..., description="The estimated cooking time")
+    ingredients: list[Ingredient] = Field(..., description="Complete list of ingredients")
+    instructions: list[str] = Field(..., description="Step-by-step cooking instructions")
+
+
+@ai_function
+def update_recipe(recipe: Recipe) -> str:
+    """Update the recipe with new or modified content.
+
+    You MUST write the complete recipe with ALL fields, even when changing only a few items.
+    When modifying an existing recipe, include ALL existing ingredients and instructions plus your changes.
+    NEVER delete existing data - only add or modify.
+
+    Args:
+        recipe: The complete recipe object with all details
+
+    Returns:
+        Confirmation that the recipe was updated
+    """
+    return "Recipe updated."
+
+
+# Create the recipe agent using tool-based approach for streaming
+agent = ChatAgent(
+    name="recipe_agent",
+    instructions="""You are a helpful recipe assistant that creates and modifies recipes.
+
+    CRITICAL RULES:
+    1. You will receive the current recipe state in the system context
+    2. To update the recipe, you MUST use the update_recipe tool
+    3. When modifying a recipe, ALWAYS include ALL existing data plus your changes in the tool call
+    4. NEVER delete existing ingredients or instructions - only add or modify
+    5. After calling the tool, provide a brief conversational message (1-2 sentences)
+
+    When creating a NEW recipe:
+    - Provide all required fields: title, skill_level, cooking_time, ingredients, instructions
+    - Use actual emojis for ingredient icons (🥕 🧄 🧅 🍅 🌿 🍗 🥩 🧀)
+    - Leave special_preferences empty unless specified
+    - Message: "Here's your recipe!" or similar
+
+    When MODIFYING or IMPROVING an existing recipe:
+    - Include ALL existing ingredients + any new ones
+    - Include ALL existing instructions + any new/modified ones
+    - Update other fields as needed
+    - Message: Explain what you improved (e.g., "I upgraded the ingredients to premium quality")
+    - When asked to "improve", enhance with:
+      * Better ingredients (upgrade quality, add complementary flavors)
+      * More detailed instructions
+      * Professional techniques
+      * Adjust skill_level if complexity changes
+      * Add relevant special_preferences
+
+    Example improvements:
+    - Upgrade "chicken" → "organic free-range chicken breast"
+    - Add herbs: basil, oregano, thyme
+    - Add aromatics: garlic, shallots
+    - Add finishing touches: lemon zest, fresh parsley
+    - Make instructions more detailed and professional
+    """,
+    chat_client=AzureOpenAIChatClient(),
+    tools=[update_recipe],
+)
+
+recipe_agent = AgentFrameworkAgent(
+    agent=agent,
+    name="RecipeAgent",
+    description="Creates and modifies recipes with streaming state updates",
+    state_schema={
+        "recipe": {"type": "object", "description": "The current recipe"},
+    },
+    predict_state_config={
+        "recipe": {"tool": "update_recipe", "tool_argument": "recipe"},
+    },
+    confirmation_strategy=RecipeConfirmationStrategy(),
+)

python/packages/ag-ui/examples/agents/research_assistant_agent.py

@@ -0,0 +1,100 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Example agent demonstrating agentic generative UI with custom events during execution."""
+
+import asyncio
+
+from agent_framework import ChatAgent, ai_function
+from agent_framework.azure import AzureOpenAIChatClient
+
+from agent_framework_ag_ui import AgentFrameworkAgent
+
+
+@ai_function
+async def research_topic(topic: str) -> str:
+    """Research a topic and generate a comprehensive report.
+
+    Args:
+        topic: The topic to research
+
+    Returns:
+        Research report
+    """
+    # Simulate multi-step research process
+    steps = [
+        ("Searching databases", 1.0),
+        ("Analyzing sources", 1.5),
+        ("Synthesizing information", 1.0),
+        ("Generating report", 0.5),
+    ]
+
+    results: list[str] = []
+    for step_name, duration in steps:
+        await asyncio.sleep(duration)
+        results.append(f"- {step_name}: completed")
+
+    return f"Research report on '{topic}':\n" + "\n".join(results)
+
+
+@ai_function
+async def create_presentation(title: str, num_slides: int) -> str:
+    """Create a presentation with multiple slides.
+
+    Args:
+        title: Presentation title
+        num_slides: Number of slides to create
+
+    Returns:
+        Presentation summary
+    """
+    # Simulate slide generation
+    slides: list[str] = []
+    for i in range(num_slides):
+        await asyncio.sleep(0.5)
+        slides.append(f"Slide {i + 1}: Content for {title}")
+
+    return f"Created presentation '{title}' with {num_slides} slides:\n" + "\n".join(slides)
+
+
+@ai_function
+async def analyze_data(dataset: str) -> str:
+    """Analyze a dataset and produce insights.
+
+    Args:
+        dataset: The dataset name to analyze
+
+    Returns:
+        Analysis results
+    """
+    # Simulate data analysis phases
+    phases = [
+        ("Loading data", 0.8),
+        ("Cleaning data", 1.0),
+        ("Running statistical analysis", 1.2),
+        ("Generating visualizations", 0.7),
+    ]
+
+    insights: list[str] = []
+    for phase_name, duration in phases:
+        await asyncio.sleep(duration)
+        insights.append(f"- {phase_name}: done")
+
+    return f"Analysis of '{dataset}':\n" + "\n".join(insights)
+
+
+agent = ChatAgent(
+    name="research_assistant",
+    instructions=(
+        "You are a research and analysis assistant. "
+        "You can research topics, create presentations, and analyze data. "
+        "Use the available tools to help users with their research needs."
+    ),
+    chat_client=AzureOpenAIChatClient(),
+    tools=[research_topic, create_presentation, analyze_data],
+)
+
+research_assistant_agent = AgentFrameworkAgent(
+    agent=agent,
+    name="ResearchAssistant",
+    description="Research assistant that emits progress events during task execution",
+)

python/packages/ag-ui/examples/agents/simple_agent.py

@@ -0,0 +1,13 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Simple agentic chat example (Feature 1: Agentic Chat)."""
+
+from agent_framework import ChatAgent
+from agent_framework.azure import AzureOpenAIChatClient
+
+# Create a simple chat agent
+agent = ChatAgent(
+    name="simple_chat_agent",
+    instructions="You are a helpful assistant. Be concise and friendly.",
+    chat_client=AzureOpenAIChatClient(),
+)

python/packages/ag-ui/examples/agents/task_planner_agent.py

@@ -0,0 +1,73 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Example agent demonstrating human-in-the-loop with function approvals."""
+
+from agent_framework import ChatAgent, ai_function
+from agent_framework.azure import AzureOpenAIChatClient
+
+from agent_framework_ag_ui import AgentFrameworkAgent, TaskPlannerConfirmationStrategy
+
+
+@ai_function(approval_mode="always_require")
+def create_calendar_event(title: str, date: str, time: str) -> str:
+    """Create a calendar event.
+
+    Args:
+        title: The event title
+        date: The event date (YYYY-MM-DD)
+        time: The event time (HH:MM)
+
+    Returns:
+        Confirmation message
+    """
+    return f"Calendar event '{title}' created for {date} at {time}"
+
+
+@ai_function(approval_mode="always_require")
+def send_email(to: str, subject: str, body: str) -> str:
+    """Send an email.
+
+    Args:
+        to: Recipient email address
+        subject: Email subject
+        body: Email body text
+
+    Returns:
+        Confirmation message
+    """
+    return f"Email sent to {to} with subject '{subject}'"
+
+
+@ai_function(approval_mode="always_require")
+def book_meeting_room(room_name: str, date: str, start_time: str, end_time: str) -> str:
+    """Book a meeting room.
+
+    Args:
+        room_name: The meeting room name
+        date: The booking date (YYYY-MM-DD)
+        start_time: Start time (HH:MM)
+        end_time: End time (HH:MM)
+
+    Returns:
+        Confirmation message
+    """
+    return f"Meeting room '{room_name}' booked for {date} from {start_time} to {end_time}"
+
+
+agent = ChatAgent(
+    name="task_planner",
+    instructions=(
+        "You are a helpful assistant that plans and executes tasks. "
+        "You have access to calendar, email, and meeting room booking functions. "
+        "All of these actions require user approval before execution."
+    ),
+    chat_client=AzureOpenAIChatClient(),
+    tools=[create_calendar_event, send_email, book_meeting_room],
+)
+
+task_planner_agent = AgentFrameworkAgent(
+    agent=agent,
+    name="TaskPlanner",
+    description="Plans and executes tasks with user approval",
+    confirmation_strategy=TaskPlannerConfirmationStrategy(),
+)

python/packages/ag-ui/examples/agents/task_steps_agent.py

@@ -0,0 +1,318 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Task steps agent demonstrating agentic generative UI (Feature 6)."""
+
+import asyncio
+from collections.abc import AsyncGenerator
+from enum import Enum
+from typing import Any
+
+from ag_ui.core import (
+    EventType,
+    MessagesSnapshotEvent,
+    RunFinishedEvent,
+    StateDeltaEvent,
+    StateSnapshotEvent,
+    TextMessageContentEvent,
+    TextMessageEndEvent,
+    TextMessageStartEvent,
+    ToolCallStartEvent,
+)
+from agent_framework import ChatAgent, ai_function
+from agent_framework.azure import AzureOpenAIChatClient
+from pydantic import BaseModel, Field
+
+from agent_framework_ag_ui import AgentFrameworkAgent
+
+
+class StepStatus(str, Enum):
+    """Status of a task step."""
+
+    PENDING = "pending"
+    COMPLETED = "completed"
+
+
+class TaskStep(BaseModel):
+    """A single step in a task."""
+
+    description: str = Field(
+        ..., description="The text of the step in gerund form (e.g., 'Digging hole', 'Opening door')"
+    )
+    status: StepStatus = Field(default=StepStatus.PENDING, description="The status of the step")
+
+
+@ai_function
+def generate_task_steps(steps: list[TaskStep]) -> str:
+    """Generate a list of task steps for completing a task.
+
+    Args:
+        steps: Complete list of task steps with descriptions and status
+
+    Returns:
+        Confirmation that steps were generated
+    """
+    return "Steps generated."
+
+
+# Create the task steps agent using tool-based approach for streaming
+agent = ChatAgent(
+    name="task_steps_agent",
+    instructions="""You are a helpful assistant that breaks down tasks into actionable steps.
+
+    When asked to perform a task, you MUST:
+    1. Use the generate_task_steps tool to create the steps
+    2. Pay attention to how many steps the user requests (if specified)
+    3. If no specific number is mentioned, use a reasonable number of steps (typically 5-10)
+    4. Each step description should be in gerund form (e.g., "Designing spacecraft", "Training astronauts")
+    5. Each step should be brief (only 2-4 words)
+    6. All steps must have status='pending'
+    7. After calling the tool, provide a brief conversational message (one sentence) saying you created the plan
+
+    Example steps for "Build a treehouse in 5 steps":
+    - "Selecting location"
+    - "Gathering materials"
+    - "Assembling frame"
+    - "Installing platform"
+    - "Adding finishing touches"
+    """,
+    chat_client=AzureOpenAIChatClient(),
+    tools=[generate_task_steps],
+)
+
+task_steps_agent = AgentFrameworkAgent(
+    agent=agent,
+    name="TaskStepsAgent",
+    description="Generates task steps with streaming state updates",
+    state_schema={
+        "steps": {"type": "array", "description": "The list of task steps"},
+    },
+    predict_state_config={
+        "steps": {
+            "tool": "generate_task_steps",
+            "tool_argument": "steps",
+        }
+    },
+    require_confirmation=False,  # Agentic generative UI updates automatically without confirmation
+)
+
+
+# Wrap the agent's run method to add step execution simulation
+class TaskStepsAgentWithExecution:
+    """Wrapper that adds step execution simulation after plan generation.
+
+    This wrapper delegates to AgentFrameworkAgent but is recognized as compatible
+    by add_agent_framework_fastapi_endpoint since it implements run_agent().
+    """
+
+    def __init__(self, base_agent: AgentFrameworkAgent):
+        """Initialize wrapper with base agent."""
+        self._base_agent = base_agent
+
+    @property
+    def name(self) -> str:
+        """Delegate to base agent."""
+        return self._base_agent.name
+
+    @property
+    def description(self) -> str:
+        """Delegate to base agent."""
+        return self._base_agent.description
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate all other attribute access to base agent."""
+        return getattr(self._base_agent, name)
+
+    async def run_agent(self, input_data: dict[str, Any]) -> AsyncGenerator[Any, None]:
+        """Run the agent and then simulate step execution."""
+        import logging
+        import uuid
+
+        logger = logging.getLogger(__name__)
+        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
+        run_finished_event: Any = None
+        tool_call_id: str | None = None
+        buffered_text_events: list[Any] = []  # Buffer text from first LLM call
+
+        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}")
+
+            match event:
+                case StateSnapshotEvent(snapshot=snapshot):
+                    final_state = snapshot
+                    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")
+                case ToolCallStartEvent(tool_call_id=call_id):
+                    tool_call_id = 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")
+                case _:
+                    logger.info(f">>> Yielding event immediately: {event_type_str}")
+                    yield event
+
+        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")
+
+            for i in range(len(steps)):
+                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")
+
+                # Send delta event with manual JSON patch format
+                delta_event = StateDeltaEvent(
+                    type=EventType.STATE_DELTA,
+                    delta=[
+                        {
+                            "op": "replace",
+                            "path": f"/steps/{i}/status",
+                            "value": "completed",
+                        }
+                    ],
+                )
+                logger.info(f">>> Yielding StateDeltaEvent for step {i + 1}")
+                yield delta_event
+
+            # Send final snapshot
+            final_snapshot = StateSnapshotEvent(
+                type=EventType.STATE_SNAPSHOT,
+                snapshot={"steps": steps},
+            )
+            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")
+
+            # Get the underlying chat agent and client
+            chat_agent = self._base_agent.agent  # type: ignore
+            chat_client = chat_agent.chat_client  # type: ignore
+
+            # Build messages for summary call
+            from agent_framework._types import ChatMessage, TextContent
+
+            original_messages = input_data.get("messages", [])
+
+            # Convert to ChatMessage objects if needed
+            messages: list[ChatMessage] = []
+            for msg in original_messages:
+                if isinstance(msg, dict):
+                    content_str = msg.get("content", "")
+                    if isinstance(content_str, str):
+                        messages.append(
+                            ChatMessage(
+                                role=msg.get("role", "user"),
+                                contents=[TextContent(text=content_str)],
+                            )
+                        )
+                elif isinstance(msg, ChatMessage):
+                    messages.append(msg)
+
+            # Add completion message
+            messages.append(
+                ChatMessage(
+                    role="user",
+                    contents=[
+                        TextContent(
+                            text="The steps have been successfully executed. Provide a brief one-sentence summary."
+                        )
+                    ],
+                )
+            )
+
+            # Stream the LLM response and manually emit text events
+            logger.info(">>> Calling chat client for summary")
+
+            message_id = str(uuid.uuid4())
+
+            try:
+                # Emit TEXT_MESSAGE_START
+                yield TextMessageStartEvent(
+                    type=EventType.TEXT_MESSAGE_START,
+                    message_id=message_id,
+                    role="assistant",
+                )
+                # Small delay to ensure START event is processed before CONTENT events
+                await asyncio.sleep(0.01)
+
+                # Stream completion
+                accumulated_text = ""
+                async for chunk in chat_client.get_streaming_response(messages=messages):
+                    # chunk is ChatResponseUpdate
+                    if hasattr(chunk, "text") and chunk.text:
+                        accumulated_text += chunk.text
+                        # Emit TEXT_MESSAGE_CONTENT
+                        yield TextMessageContentEvent(
+                            type=EventType.TEXT_MESSAGE_CONTENT,
+                            message_id=message_id,
+                            delta=chunk.text,
+                        )
+
+                # Emit TEXT_MESSAGE_END
+                yield TextMessageEndEvent(
+                    type=EventType.TEXT_MESSAGE_END,
+                    message_id=message_id,
+                )
+                logger.info(f">>> Summary complete: {accumulated_text}")
+
+                # Build complete message for persistence
+                summary_message = {
+                    "role": "assistant",
+                    "content": accumulated_text,
+                    "id": message_id,
+                }
+                final_messages = list(original_messages)
+                final_messages.append(summary_message)
+
+                # Emit MessagesSnapshotEvent to persist in history
+                yield MessagesSnapshotEvent(
+                    type=EventType.MESSAGES_SNAPSHOT,
+                    messages=final_messages,
+                )
+            except Exception as 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
+                yield TextMessageStartEvent(
+                    type=EventType.TEXT_MESSAGE_START,
+                    message_id=error_message_id,
+                    role="assistant",
+                )
+                # Yield error message content
+                yield TextMessageContentEvent(
+                    type=EventType.TEXT_MESSAGE_CONTENT,
+                    message_id=error_message_id,
+                    delta=f"[Summary generation error: {e!s}]",
+                )
+                # Yield TEXT_MESSAGE_END for error
+                yield TextMessageEndEvent(
+                    type=EventType.TEXT_MESSAGE_END,
+                    message_id=error_message_id,
+                )
+        else:
+            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")
+            yield run_finished_event
+
+
+# Export the wrapped agent
+task_steps_agent_wrapped = TaskStepsAgentWithExecution(task_steps_agent)

python/packages/ag-ui/examples/agents/ui_generator_agent.py

@@ -0,0 +1,119 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Example agent demonstrating Tool-based Generative UI (Feature 5)."""
+
+from typing import Any
+
+from agent_framework import ChatAgent, ai_function
+from agent_framework.azure import AzureOpenAIChatClient
+
+from agent_framework_ag_ui import AgentFrameworkAgent
+
+
+@ai_function
+def generate_haiku(english: list[str], japanese: list[str], image_name: str | None, gradient: str) -> str:
+    """Generate a haiku with image and gradient background (FRONTEND_RENDER).
+
+    This tool generates UI for displaying a haiku with an image and gradient background.
+    The frontend should render this as a custom haiku component.
+
+    Args:
+        english: English haiku lines (exactly 3 lines)
+        japanese: Japanese haiku lines (exactly 3 lines)
+        image_name: Image filename for visual accompaniment. Must be one of:
+            - "Osaka_Castle_Turret_Stone_Wall_Pine_Trees_Daytime.jpg"
+            - "Tokyo_Skyline_Night_Tokyo_Tower_Mount_Fuji_View.jpg"
+            - "Itsukushima_Shrine_Miyajima_Floating_Torii_Gate_Sunset_Long_Exposure.jpg"
+            - "Takachiho_Gorge_Waterfall_River_Lush_Greenery_Japan.jpg"
+            - "Bonsai_Tree_Potted_Japanese_Art_Green_Foliage.jpeg"
+            - "Shirakawa-go_Gassho-zukuri_Thatched_Roof_Village_Aerial_View.jpg"
+            - "Ginkaku-ji_Silver_Pavilion_Kyoto_Japanese_Garden_Pond_Reflection.jpg"
+            - "Senso-ji_Temple_Asakusa_Cherry_Blossoms_Kimono_Umbrella.jpg"
+            - "Cherry_Blossoms_Sakura_Night_View_City_Lights_Japan.jpg"
+            - "Mount_Fuji_Lake_Reflection_Cherry_Blossoms_Sakura_Spring.jpg"
+        gradient: CSS gradient string for background (e.g., "linear-gradient(135deg, #667eea 0%, #764ba2 100%)")
+
+    Returns:
+        Haiku metadata for frontend rendering
+    """
+    return f"Haiku generated with image: {image_name}"
+
+
+@ai_function
+def create_chart(chart_type: str, data_points: list[dict[str, Any]], title: str) -> str:
+    """Create an interactive chart (FRONTEND_RENDER).
+
+    This tool creates chart specifications for frontend rendering.
+    The frontend should render this as an interactive chart component.
+
+    Args:
+        chart_type: Type of chart (bar, line, pie, scatter)
+        data_points: Data points for the chart
+        title: Chart title
+
+    Returns:
+        Chart specification for frontend rendering
+    """
+    return f"Chart '{title}' created with {len(data_points)} data points"
+
+
+@ai_function
+def display_timeline(events: list[dict[str, Any]], start_date: str, end_date: str) -> str:
+    """Display an interactive timeline (FRONTEND_RENDER).
+
+    This tool creates timeline specifications for frontend rendering.
+    The frontend should render this as an interactive timeline component.
+
+    Args:
+        events: Events to display on the timeline
+        start_date: Timeline start date
+        end_date: Timeline end date
+
+    Returns:
+        Timeline specification for frontend rendering
+    """
+    return f"Timeline created with {len(events)} events from {start_date} to {end_date}"
+
+
+@ai_function
+def show_comparison_table(items: list[dict[str, Any]], columns: list[str]) -> str:
+    """Show a comparison table (FRONTEND_RENDER).
+
+    This tool creates table specifications for frontend rendering.
+    The frontend should render this as an interactive comparison table.
+
+    Args:
+        items: Items to compare
+        columns: Column names
+
+    Returns:
+        Table specification for frontend rendering
+    """
+    return f"Comparison table created with {len(items)} items and {len(columns)} columns"
+
+
+# Create the UI generator agent using tool-based approach with forced tool usage
+agent = ChatAgent(
+    name="ui_generator",
+    instructions="""You MUST use the provided tools to generate content. Never respond with plain text descriptions.
+
+    For haiku requests:
+    - Call generate_haiku tool with all 4 required parameters
+    - English: 3 lines
+    - Japanese: 3 lines
+    - image_name: Choose from available images
+    - gradient: CSS gradient string
+
+    For other requests, use the appropriate tool (create_chart, display_timeline, show_comparison_table).
+    """,
+    chat_client=AzureOpenAIChatClient(),
+    tools=[generate_haiku, create_chart, display_timeline, show_comparison_table],
+    # Force tool usage - the LLM MUST call a tool, cannot respond with plain text
+    chat_options={"tool_choice": "required"},
+)
+
+ui_generator_agent = AgentFrameworkAgent(
+    agent=agent,
+    name="UIGenerator",
+    description="Generates custom UI components through tool calls",
+)

python/packages/ag-ui/examples/agents/weather_agent.py

@@ -0,0 +1,71 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Weather agent example demonstrating backend tool rendering."""
+
+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 the current weather for a location.
+
+    Args:
+        location: The city or location to get weather for.
+
+    Returns:
+        Weather information as a dictionary with temperatures in Celsius.
+    """
+    # Simulated weather data with structured format (temperatures in Celsius for dojo UI)
+    weather_data = {
+        "seattle": {"temperature": 11, "conditions": "rainy", "humidity": 75, "wind_speed": 12, "feels_like": 10},
+        "san francisco": {"temperature": 14, "conditions": "foggy", "humidity": 85, "wind_speed": 8, "feels_like": 13},
+        "new york city": {"temperature": 18, "conditions": "sunny", "humidity": 60, "wind_speed": 10, "feels_like": 17},
+        "miami": {"temperature": 29, "conditions": "hot and humid", "humidity": 90, "wind_speed": 5, "feels_like": 32},
+        "chicago": {"temperature": 9, "conditions": "windy", "humidity": 65, "wind_speed": 20, "feels_like": 6},
+    }
+
+    location_lower = location.lower()
+    if location_lower in weather_data:
+        return weather_data[location_lower]
+
+    return {
+        "temperature": 21,
+        "conditions": "partly cloudy",
+        "humidity": 50,
+        "wind_speed": 10,
+        "feels_like": 20,
+    }
+
+
+@ai_function
+def get_forecast(location: str, days: int = 3) -> str:
+    """Get the weather forecast for a location.
+
+    Args:
+        location: The city or location to get forecast for.
+        days: Number of days to forecast (default: 3).
+
+    Returns:
+        Forecast information string.
+    """
+    forecast: list[str] = []
+    for day in range(1, min(days, 7) + 1):
+        forecast.append(f"Day {day}: Partly cloudy, {60 + day * 2}°F")
+
+    return f"{days}-day forecast for {location}:\n" + "\n".join(forecast)
+
+
+# Create the weather agent
+weather_agent = ChatAgent(
+    name="weather_agent",
+    instructions=(
+        "You are a helpful weather assistant. "
+        "Use the get_weather and get_forecast functions to help users with weather information. "
+        "Always provide friendly and informative responses."
+    ),
+    chat_client=AzureOpenAIChatClient(),
+    tools=[get_weather, get_forecast],
+)

python/packages/ag-ui/examples/server/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) Microsoft. All rights reserved.

python/packages/ag-ui/examples/server/api/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""API endpoints for AG-UI examples."""

python/packages/ag-ui/examples/server/api/backend_tool_rendering.py

@@ -0,0 +1,22 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Backend tool rendering endpoint."""
+
+from fastapi import FastAPI
+
+from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint
+
+from ...agents.weather_agent import weather_agent
+
+
+def register_backend_tool_rendering(app: FastAPI) -> None:
+    """Register the backend tool rendering endpoint.
+
+    Args:
+        app: The FastAPI application.
+    """
+    add_agent_framework_fastapi_endpoint(
+        app,
+        weather_agent,
+        "/backend_tool_rendering",
+    )

python/packages/ag-ui/examples/server/main.py

@@ -0,0 +1,129 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Example FastAPI server with AG-UI endpoints."""
+
+import logging
+import os
+
+import uvicorn
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from agent_framework_ag_ui import add_agent_framework_fastapi_endpoint
+
+from ..agents.document_writer_agent import document_writer_agent
+from ..agents.human_in_the_loop_agent import human_in_the_loop_agent
+from ..agents.recipe_agent import recipe_agent
+from ..agents.simple_agent import agent as simple_agent
+from ..agents.task_steps_agent import task_steps_agent_wrapped as task_steps_agent  # Custom wrapper
+from ..agents.ui_generator_agent import ui_generator_agent
+from ..agents.weather_agent import weather_agent
+
+# Configure logging to file and console (disabled by default - set ENABLE_DEBUG_LOGGING=1 to enable)
+if os.getenv("ENABLE_DEBUG_LOGGING"):
+    log_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..", "ag_ui_server.log")
+
+    # Remove any existing handlers
+    root_logger = logging.getLogger()
+    for handler in root_logger.handlers[:]:
+        root_logger.removeHandler(handler)
+
+    # Configure new handlers
+    file_handler = logging.FileHandler(log_file, mode="w")
+    file_handler.setLevel(logging.INFO)
+    file_handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
+
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(logging.INFO)
+    console_handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
+
+    root_logger.addHandler(file_handler)
+    root_logger.addHandler(console_handler)
+    root_logger.setLevel(logging.INFO)
+
+    # Explicitly set log levels for our modules
+    logging.getLogger("agent_framework_ag_ui").setLevel(logging.INFO)
+    logging.getLogger("agent_framework").setLevel(logging.INFO)
+
+    logger = logging.getLogger(__name__)
+    logger.info(f"AG-UI Examples Server starting... Logs writing to: {log_file}")
+
+app = FastAPI(title="Agent Framework AG-UI Example Server")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Agentic Chat - basic chat agent
+add_agent_framework_fastapi_endpoint(
+    app=app,
+    agent=simple_agent,
+    path="/agentic_chat",
+)
+
+# Backend Tool Rendering - agent with tools
+add_agent_framework_fastapi_endpoint(
+    app=app,
+    agent=weather_agent,
+    path="/backend_tool_rendering",
+)
+
+# Shared State - recipe agent with structured output
+add_agent_framework_fastapi_endpoint(
+    app=app,
+    agent=recipe_agent,
+    path="/shared_state",
+)
+
+# Predictive State Updates - document writer with predictive state
+add_agent_framework_fastapi_endpoint(
+    app=app,
+    agent=document_writer_agent,
+    path="/predictive_state_updates",
+)
+
+# Human in the Loop - human-in-the-loop agent with step customization
+add_agent_framework_fastapi_endpoint(
+    app=app,
+    agent=human_in_the_loop_agent,
+    path="/human_in_the_loop",
+    state_schema={"steps": {"type": "array"}},
+    predict_state_config={"steps": {"tool": "generate_task_steps", "tool_argument": "steps"}},
+)
+
+# Agentic Generative UI - task steps agent with streaming state updates
+add_agent_framework_fastapi_endpoint(
+    app=app,
+    agent=task_steps_agent,  # type: ignore[arg-type]
+    path="/agentic_generative_ui",
+)
+
+# Tool-based Generative UI - UI generator with frontend-rendered tools
+add_agent_framework_fastapi_endpoint(
+    app=app,
+    agent=ui_generator_agent,
+    path="/tool_based_generative_ui",
+)
+
+
+def main():
+    """Run the server."""
+    port = int(os.getenv("PORT", "8888"))
+    host = os.getenv("HOST", "127.0.0.1")
+
+    # Use log_config=None to prevent uvicorn from reconfiguring logging
+    # This preserves our file + console logging setup
+    uvicorn.run(
+        app,
+        host=host,
+        port=port,
+        log_config=None,
+    )
+
+
+if __name__ == "__main__":
+    main()

python/packages/ag-ui/getting_started/README.md

@@ -0,0 +1,705 @@
+# Getting Started with AG-UI (Python)
+
+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.
+
+## What is AG-UI?
+
+AG-UI is a protocol that enables:
+- **Remote agent hosting**: Host AI agents as web services that can be accessed by multiple clients
+- **Streaming responses**: Real-time streaming of agent responses using Server-Sent Events (SSE)
+- **Standardized communication**: Consistent message format for agent interactions
+- **Thread management**: Maintain conversation context across multiple requests
+- **Advanced features**: Human-in-the-loop, state management, tool rendering
+
+## Prerequisites
+
+Before you begin, ensure you have the following:
+
+- Python 3.10 or later
+- Azure OpenAI service endpoint and deployment configured
+- Azure CLI installed and authenticated (for DefaultAzureCredential)
+- User has the `Cognitive Services OpenAI Contributor` role for the Azure OpenAI resource
+
+**Note**: These samples use Azure OpenAI models. For more information, see [how to deploy Azure OpenAI models with Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/how-to/deploy-models-openai).
+
+**Note**: These samples use `DefaultAzureCredential` for authentication. Make sure you're authenticated with Azure (e.g., via `az login`, or environment variables). For more information, see the [Azure Identity documentation](https://learn.microsoft.com/python/api/azure-identity/azure.identity.defaultazurecredential).
+
+> **Warning**
+> The AG-UI protocol is still under development and subject to change.
+> We will keep these samples updated as the protocol evolves.
+
+## Step 1: Creating an AG-UI Server
+
+The AG-UI server hosts your AI agent and exposes it via HTTP endpoints using FastAPI.
+
+### Install Required Packages
+
+```bash
+pip install agent-framework-ag-ui agent-framework-core fastapi uvicorn
+```
+
+Or using uv:
+
+```bash
+uv pip install agent-framework-ag-ui agent-framework-core fastapi uvicorn
+```
+
+### Server Code
+
+Create a file named `server.py`:
+
+```python
+# Copyright (c) Microsoft. All rights reserved.
+
+"""AG-UI server example."""
+
+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 fastapi import FastAPI
+
+# Read required configuration
+endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
+deployment_name = os.environ.get("AZURE_OPENAI_DEPLOYMENT_NAME")
+
+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")
+
+# Create the AI agent
+agent = ChatAgent(
+    name="AGUIAssistant",
+    instructions="You are a helpful assistant.",
+    chat_client=AzureOpenAIChatClient(
+        endpoint=endpoint,
+        deployment_name=deployment_name,
+    ),
+)
+
+# Create FastAPI app
+app = FastAPI(title="AG-UI Server")
+
+# Register the AG-UI endpoint
+add_agent_framework_fastapi_endpoint(app, agent, "/")
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="127.0.0.1", port=5100)
+```
+
+### Key Concepts
+
+- **`add_agent_framework_fastapi_endpoint`**: Registers the AG-UI endpoint with automatic request/response handling and SSE streaming
+- **`ChatAgent`**: The agent that will handle incoming requests
+- **FastAPI Integration**: Uses FastAPI's native async support for streaming responses
+- **Instructions**: The agent is created with default instructions, which can be overridden by client messages
+- **Configuration**: `AzureOpenAIChatClient` can read from environment variables (`AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_CHAT_DEPLOYMENT_NAME`, `AZURE_OPENAI_API_KEY`) or accept parameters directly
+
+**Alternative (simpler)**: Use environment variables only:
+
+```python
+# No need to read environment variables manually
+agent = ChatAgent(
+    name="AGUIAssistant",
+    instructions="You are a helpful assistant.",
+    chat_client=AzureOpenAIChatClient(),  # Reads from environment automatically
+)
+```
+
+### Configure and Run the Server
+
+Set the required environment variables:
+
+```bash
+export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+export AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4o-mini"
+# Optional: Set API key if not using DefaultAzureCredential
+# export AZURE_OPENAI_API_KEY="your-api-key"
+```
+
+Run the server:
+
+```bash
+python server.py
+```
+
+Or using uvicorn directly:
+
+```bash
+uvicorn server:app --host 127.0.0.1 --port 5100
+```
+
+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.
+
+### Install Required Packages
+
+```bash
+pip install httpx
+```
+
+### Client Code
+
+Create a file named `client.py`:
+
+```python
+# Copyright (c) Microsoft. All rights reserved.
+
+"""AG-UI client example."""
+
+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
+
+
+async def main():
+    """Main client loop."""
+    # 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)
+
+    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
+
+            # Send message and display streaming response
+            print("\n", end="")
+            async for event in client.send_message(message):
+                event_type = event.get("type", "")
+
+                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")
+
+                elif event_type == "TEXT_MESSAGE_CONTENT":
+                    # Stream text content in cyan
+                    print(f"\033[96m{event.get('delta', '')}\033[0m", 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")
+
+                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()
+
+    except KeyboardInterrupt:
+        print("\n\nExiting...")
+    except Exception as e:
+        print(f"\n\033[91mAn error occurred: {e}\033[0m")
+
+
+if __name__ == "__main__":
+    asyncio.run(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
+
+### Configure and Run the Client
+
+Optionally set a custom server URL:
+
+```bash
+export AGUI_SERVER_URL="http://127.0.0.1:5100/"
+```
+
+Run the client (in a separate terminal):
+
+```bash
+python client.py
+```
+
+## Step 3: Testing the Complete System
+
+### Expected Output
+
+```
+$ python client.py
+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,
+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](../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
+
+Ensure the server is running before starting the client:
+
+```bash
+# Terminal 1
+python server.py
+
+# Terminal 2 (after server starts)
+python client.py
+```
+
+### Authentication Errors
+
+Make sure you're authenticated with Azure:
+
+```bash
+az login
+```
+
+Verify you have the correct role assignment on the Azure OpenAI resource.
+
+### Streaming Not Working
+
+Check that your client timeout is sufficient:
+
+```python
+httpx.AsyncClient(timeout=60.0)  # 60 seconds should be enough
+```
+
+For long-running agents, increase the timeout accordingly.
+
+### No Events Received
+
+Ensure you're using the correct `Accept` header:
+
+```python
+headers={"Accept": "text/event-stream"}
+```
+
+And parsing SSE format correctly (lines starting with `data: `).
+
+### Thread Context Lost
+
+The client automatically manages thread continuity. If context is lost:
+
+1. Check that `threadId` is being captured from `RUN_STARTED` events
+2. Ensure the same client instance is used across messages
+3. Verify the server is receiving the `thread_id` in subsequent requests
+
+### Event Type Mismatches
+
+Remember that event types are UPPERCASE with underscores (`RUN_STARTED`, not `run_started`) and field names are camelCase (`threadId`, not `thread_id`).
+
+### Import Errors
+
+Make sure all packages are installed:
+
+```bash
+pip install agent-framework-ag-ui agent-framework-core fastapi uvicorn httpx
+```
+
+Or check your virtual environment is activated:
+
+```bash
+source venv/bin/activate  # Linux/macOS
+venv\Scripts\activate     # Windows
+```

python/packages/ag-ui/getting_started/client.py

@@ -0,0 +1,122 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""AG-UI client example."""
+
+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
+
+
+async def main():
+    """Main client loop."""
+    # 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)
+
+    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
+
+            # Send message and display streaming response
+            print("\n", end="")
+            async for event in client.send_message(message):
+                event_type = event.get("type", "")
+
+                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")
+
+                elif event_type == "TEXT_MESSAGE_CONTENT":
+                    # Stream text content in cyan
+                    print(f"\033[96m{event.get('delta', '')}\033[0m", 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")
+
+                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()
+
+    except KeyboardInterrupt:
+        print("\n\nExiting...")
+    except Exception as e:
+        print(f"\n\033[91mAn error occurred: {e}\033[0m")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

python/packages/ag-ui/getting_started/server.py

@@ -0,0 +1,44 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""AG-UI server example."""
+
+import os
+
+from agent_framework import ChatAgent
+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()
+
+# Read required configuration
+endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
+deployment_name = os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME")
+
+if not endpoint:
+    raise ValueError("AZURE_OPENAI_ENDPOINT environment variable is required")
+if not deployment_name:
+    raise ValueError("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME environment variable is required")
+
+# Create the AI agent
+agent = ChatAgent(
+    name="AGUIAssistant",
+    instructions="You are a helpful assistant.",
+    chat_client=AzureOpenAIChatClient(
+        endpoint=endpoint,
+        deployment_name=deployment_name,
+    ),
+)
+
+# Create FastAPI app
+app = FastAPI(title="AG-UI Server")
+
+# Register the AG-UI endpoint
+add_agent_framework_fastapi_endpoint(app, agent, "/")
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="127.0.0.1", port=5100)

python/packages/ag-ui/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "agent-framework-ag-ui"
+version = "1.0.0b251105"
+description = "AG-UI protocol integration for Agent Framework"
+readme = "README.md"
+license-files = ["LICENSE"]
+authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
+requires-python = ">=3.10"
+urls.homepage = "https://aka.ms/agent-framework"
+urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
+urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
+urls.issues = "https://github.com/microsoft/agent-framework/issues"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+    "agent-framework-core",
+    "ag-ui-protocol>=0.1.9",
+    "fastapi>=0.115.0",
+    "uvicorn>=0.30.0"
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.24.0",
+    "httpx>=0.27.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agent_framework_ag_ui"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+
+[tool.pyright]
+exclude = ["tests", "examples"]
+typeCheckingMode = "basic"
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+
+[tool.poe.tasks]
+mypy = "mypy --config-file $POE_ROOT/pyproject.toml agent_framework_ag_ui"
+test = "pytest --cov=agent_framework_ag_ui --cov-report=term-missing:skip-covered tests"

python/packages/ag-ui/tests/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) Microsoft. All rights reserved.

python/packages/ag-ui/tests/test_agent_wrapper_comprehensive.py

@@ -0,0 +1,577 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Comprehensive tests for AgentFrameworkAgent (_agent.py)."""
+
+import json
+
+import pytest
+from agent_framework import ChatAgent, TextContent
+from agent_framework._types import ChatResponseUpdate
+
+
+async def test_agent_initialization_basic():
+    """Test basic agent initialization without state schema."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    assert wrapper.name == "test_agent"
+    assert wrapper.agent == agent
+    assert wrapper.config.state_schema == {}
+    assert wrapper.config.predict_state_config == {}
+
+
+async def test_agent_initialization_with_state_schema():
+    """Test agent initialization with state_schema."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    state_schema = {"document": {"type": "string"}}
+    wrapper = AgentFrameworkAgent(agent=agent, state_schema=state_schema)
+
+    assert wrapper.config.state_schema == state_schema
+
+
+async def test_agent_initialization_with_predict_state_config():
+    """Test agent initialization with predict_state_config."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    predict_config = {"document": {"tool": "write_doc", "tool_argument": "content"}}
+    wrapper = AgentFrameworkAgent(agent=agent, predict_state_config=predict_config)
+
+    assert wrapper.config.predict_state_config == predict_config
+
+
+async def test_run_started_event_emission():
+    """Test RunStartedEvent is emitted at start of run."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    input_data = {"messages": [{"role": "user", "content": "Hi"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # First event should be RunStartedEvent
+    assert events[0].type == "RUN_STARTED"
+    assert events[0].run_id is not None
+    assert events[0].thread_id is not None
+
+
+async def test_predict_state_custom_event_emission():
+    """Test PredictState CustomEvent is emitted when predict_state_config is present."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    predict_config = {
+        "document": {"tool": "write_doc", "tool_argument": "content"},
+        "summary": {"tool": "summarize", "tool_argument": "text"},
+    }
+    wrapper = AgentFrameworkAgent(agent=agent, predict_state_config=predict_config)
+
+    input_data = {"messages": [{"role": "user", "content": "Hi"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Find PredictState event
+    predict_events = [e for e in events if e.type == "CUSTOM" and e.name == "PredictState"]
+    assert len(predict_events) == 1
+
+    predict_value = predict_events[0].value
+    assert len(predict_value) == 2
+    assert {"state_key": "document", "tool": "write_doc", "tool_argument": "content"} in predict_value
+    assert {"state_key": "summary", "tool": "summarize", "tool_argument": "text"} in predict_value
+
+
+async def test_initial_state_snapshot_with_schema():
+    """Test initial StateSnapshotEvent emission when state_schema present."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    state_schema = {"document": {"type": "string"}}
+    wrapper = AgentFrameworkAgent(agent=agent, state_schema=state_schema)
+
+    input_data = {
+        "messages": [{"role": "user", "content": "Hi"}],
+        "state": {"document": "Initial content"},
+    }
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Find StateSnapshotEvent
+    snapshot_events = [e for e in events if e.type == "STATE_SNAPSHOT"]
+    assert len(snapshot_events) >= 1
+
+    # First snapshot should have initial state
+    assert snapshot_events[0].snapshot == {"document": "Initial content"}
+
+
+async def test_state_initialization_object_type():
+    """Test state initialization with object type in schema."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    state_schema = {"recipe": {"type": "object", "properties": {}}}
+    wrapper = AgentFrameworkAgent(agent=agent, state_schema=state_schema)
+
+    input_data = {"messages": [{"role": "user", "content": "Hi"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Find StateSnapshotEvent
+    snapshot_events = [e for e in events if e.type == "STATE_SNAPSHOT"]
+    assert len(snapshot_events) >= 1
+
+    # Should initialize as empty object
+    assert snapshot_events[0].snapshot == {"recipe": {}}
+
+
+async def test_state_initialization_array_type():
+    """Test state initialization with array type in schema."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    state_schema = {"steps": {"type": "array", "items": {}}}
+    wrapper = AgentFrameworkAgent(agent=agent, state_schema=state_schema)
+
+    input_data = {"messages": [{"role": "user", "content": "Hi"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Find StateSnapshotEvent
+    snapshot_events = [e for e in events if e.type == "STATE_SNAPSHOT"]
+    assert len(snapshot_events) >= 1
+
+    # Should initialize as empty array
+    assert snapshot_events[0].snapshot == {"steps": []}
+
+
+async def test_run_finished_event_emission():
+    """Test RunFinishedEvent is emitted at end of run."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    input_data = {"messages": [{"role": "user", "content": "Hi"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Last event should be RunFinishedEvent
+    assert events[-1].type == "RUN_FINISHED"
+
+
+async def test_tool_result_confirm_changes_accepted():
+    """Test confirm_changes tool result handling when accepted."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Document updated")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(
+        agent=agent,
+        state_schema={"document": {"type": "string"}},
+        predict_state_config={"document": {"tool": "write_doc", "tool_argument": "content"}},
+    )
+
+    # Simulate tool result message with acceptance
+    tool_result = {"accepted": True, "steps": []}
+    input_data = {
+        "messages": [
+            {
+                "role": "tool",  # Tool result from UI
+                "content": json.dumps(tool_result),
+                "toolCallId": "confirm_call_123",
+            }
+        ],
+        "state": {"document": "Updated content"},
+    }
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should emit text message confirming acceptance
+    text_content_events = [e for e in events if e.type == "TEXT_MESSAGE_CONTENT"]
+    assert len(text_content_events) > 0
+    # Should contain confirmation message mentioning the state key or generic confirmation
+    confirmation_found = any(
+        "document" in e.delta.lower()
+        or "confirm" in e.delta.lower()
+        or "applied" in e.delta.lower()
+        or "changes" in e.delta.lower()
+        for e in text_content_events
+    )
+    assert confirmation_found, f"No confirmation in deltas: {[e.delta for e in text_content_events]}"
+
+
+async def test_tool_result_confirm_changes_rejected():
+    """Test confirm_changes tool result handling when rejected."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="OK")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    # Simulate tool result message with rejection
+    tool_result = {"accepted": False, "steps": []}
+    input_data = {
+        "messages": [
+            {
+                "role": "tool",
+                "content": json.dumps(tool_result),
+                "toolCallId": "confirm_call_123",
+            }
+        ],
+    }
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should emit text message asking what to change
+    text_content_events = [e for e in events if e.type == "TEXT_MESSAGE_CONTENT"]
+    assert len(text_content_events) > 0
+    assert any("what would you like me to change" in e.delta.lower() for e in text_content_events)
+
+
+async def test_tool_result_function_approval_accepted():
+    """Test function approval tool result when steps are accepted."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="OK")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    # Simulate tool result with multiple steps
+    tool_result = {
+        "accepted": True,
+        "steps": [
+            {"id": "step1", "description": "Send email", "status": "enabled"},
+            {"id": "step2", "description": "Create calendar event", "status": "enabled"},
+        ],
+    }
+    input_data = {
+        "messages": [
+            {
+                "role": "tool",
+                "content": json.dumps(tool_result),
+                "toolCallId": "approval_call_123",
+            }
+        ],
+    }
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should list enabled steps
+    text_content_events = [e for e in events if e.type == "TEXT_MESSAGE_CONTENT"]
+    assert len(text_content_events) > 0
+
+    # Concatenate all text content
+    full_text = "".join(e.delta for e in text_content_events)
+    assert "executing" in full_text.lower()
+    assert "2 approved steps" in full_text.lower()
+    assert "send email" in full_text.lower()
+    assert "create calendar event" in full_text.lower()
+
+
+async def test_tool_result_function_approval_rejected():
+    """Test function approval tool result when rejected."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="OK")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    # Simulate tool result rejection with steps
+    tool_result = {
+        "accepted": False,
+        "steps": [{"id": "step1", "description": "Send email", "status": "disabled"}],
+    }
+    input_data = {
+        "messages": [
+            {
+                "role": "tool",
+                "content": json.dumps(tool_result),
+                "toolCallId": "approval_call_123",
+            }
+        ],
+    }
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should ask what to change about the plan
+    text_content_events = [e for e in events if e.type == "TEXT_MESSAGE_CONTENT"]
+    assert len(text_content_events) > 0
+    assert any("what would you like me to change about the plan" in e.delta.lower() for e in text_content_events)
+
+
+async def test_thread_metadata_tracking():
+    """Test that thread metadata includes ag_ui_thread_id and ag_ui_run_id."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    thread_metadata = {}
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            # Capture thread metadata from kwargs
+            nonlocal thread_metadata
+            if "thread" in kwargs:
+                thread_metadata = kwargs["thread"].metadata
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    input_data = {
+        "messages": [{"role": "user", "content": "Hi"}],
+        "thread_id": "test_thread_123",
+        "run_id": "test_run_456",
+    }
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Check thread metadata was set
+    # Note: This test may need adjustment based on actual thread passing mechanism
+
+
+async def test_state_context_injection():
+    """Test that current state is injected into thread metadata."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    thread_metadata = {}
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            # Track if state context message was added
+            nonlocal thread_metadata
+            # In actual implementation, thread is passed and state is in metadata
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(
+        agent=agent,
+        state_schema={"document": {"type": "string"}},
+    )
+
+    input_data = {
+        "messages": [{"role": "user", "content": "Hi"}],
+        "state": {"document": "Test content"},
+    }
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # State should be injected - this is validated by agent execution flow
+
+
+async def test_no_messages_provided():
+    """Test handling when no messages are provided."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    input_data = {"messages": []}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should emit RunStartedEvent and RunFinishedEvent only
+    assert len(events) == 2
+    assert events[0].type == "RUN_STARTED"
+    assert events[-1].type == "RUN_FINISHED"
+
+
+async def test_message_end_event_emission():
+    """Test TextMessageEndEvent is emitted for assistant messages."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello world")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    input_data = {"messages": [{"role": "user", "content": "Hi"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should have TextMessageEndEvent before RunFinishedEvent
+    end_events = [e for e in events if e.type == "TEXT_MESSAGE_END"]
+    assert len(end_events) == 1
+
+    # EndEvent should come before FinishedEvent
+    end_index = events.index(end_events[0])
+    finished_index = events.index([e for e in events if e.type == "RUN_FINISHED"][0])
+    assert end_index < finished_index
+
+
+async def test_error_handling_with_exception():
+    """Test that exceptions during agent execution are re-raised."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class FailingChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            if False:
+                yield
+            raise RuntimeError("Simulated failure")
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=FailingChatClient())
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    input_data = {"messages": [{"role": "user", "content": "Hi"}]}
+
+    with pytest.raises(RuntimeError, match="Simulated failure"):
+        async for event in wrapper.run_agent(input_data):
+            pass
+
+
+async def test_json_decode_error_in_tool_result():
+    """Test handling of JSONDecodeError when parsing tool result."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Fallback response")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    # Send invalid JSON as tool result
+    input_data = {
+        "messages": [
+            {
+                "role": "tool",
+                "content": "invalid json {not valid}",
+                "toolCallId": "call_123",
+            }
+        ],
+    }
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should fall through to normal agent processing
+    text_events = [e for e in events if e.type == "TEXT_MESSAGE_CONTENT"]
+    assert len(text_events) > 0
+    assert text_events[0].delta == "Fallback response"
+
+
+async def test_suppressed_summary_with_document_state():
+    """Test suppressed summary uses document state for confirmation message."""
+    from agent_framework_ag_ui import AgentFrameworkAgent, DocumentWriterConfirmationStrategy
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Response")])
+
+    agent = ChatAgent(name="test_agent", instructions="Test", chat_client=MockChatClient())
+    wrapper = AgentFrameworkAgent(
+        agent=agent,
+        state_schema={"document": {"type": "string"}},
+        predict_state_config={"document": {"tool": "write_doc", "tool_argument": "content"}},
+        confirmation_strategy=DocumentWriterConfirmationStrategy(),
+    )
+
+    # Simulate confirmation with document state
+    tool_result = {"accepted": True, "steps": []}
+    input_data = {
+        "messages": [
+            {
+                "role": "tool",
+                "content": json.dumps(tool_result),
+                "toolCallId": "confirm_123",
+            }
+        ],
+        "state": {"document": "This is the beginning of a document. It contains important information."},
+    }
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should generate fallback summary from document state
+    text_events = [e for e in events if e.type == "TEXT_MESSAGE_CONTENT"]
+    assert len(text_events) > 0
+    # Should contain some reference to the document
+    full_text = "".join(e.delta for e in text_events)
+    assert "written" in full_text.lower() or "document" in full_text.lower()

python/packages/ag-ui/tests/test_backend_tool_rendering.py

@@ -0,0 +1,124 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for backend tool rendering."""
+
+from ag_ui.core import (
+    TextMessageContentEvent,
+    TextMessageStartEvent,
+    ToolCallArgsEvent,
+    ToolCallEndEvent,
+    ToolCallResultEvent,
+    ToolCallStartEvent,
+)
+from agent_framework import AgentRunResponseUpdate, FunctionCallContent, FunctionResultContent, TextContent
+
+from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+
+async def test_tool_call_flow():
+    """Test complete tool call flow: call -> args -> end -> result."""
+    bridge = AgentFrameworkEventBridge(run_id="test-run", thread_id="test-thread")
+
+    # Step 1: Tool call starts
+    tool_call = FunctionCallContent(
+        call_id="weather-123",
+        name="get_weather",
+        arguments={"location": "Seattle"},
+    )
+
+    update1 = AgentRunResponseUpdate(contents=[tool_call])
+    events1 = await bridge.from_agent_run_update(update1)
+
+    # Should have: ToolCallStartEvent, ToolCallArgsEvent
+    assert len(events1) == 2
+    assert isinstance(events1[0], ToolCallStartEvent)
+    assert isinstance(events1[1], ToolCallArgsEvent)
+
+    start_event = events1[0]
+    assert start_event.tool_call_id == "weather-123"
+    assert start_event.tool_call_name == "get_weather"
+
+    args_event = events1[1]
+    assert "Seattle" in args_event.delta
+
+    # Step 2: Tool result comes back
+    tool_result = FunctionResultContent(
+        call_id="weather-123",
+        result="Weather in Seattle: Rainy, 52°F",
+    )
+
+    update2 = AgentRunResponseUpdate(contents=[tool_result])
+    events2 = await bridge.from_agent_run_update(update2)
+
+    # Should have: ToolCallEndEvent, ToolCallResultEvent, MessagesSnapshotEvent
+    assert len(events2) == 3
+    assert isinstance(events2[0], ToolCallEndEvent)
+    assert isinstance(events2[1], ToolCallResultEvent)
+
+    end_event = events2[0]
+    assert end_event.tool_call_id == "weather-123"
+
+    result_event = events2[1]
+    assert result_event.tool_call_id == "weather-123"
+    assert "Seattle" in result_event.content
+    assert "Rainy" in result_event.content
+
+
+async def test_text_with_tool_call():
+    """Test agent response with both text and tool calls."""
+    bridge = AgentFrameworkEventBridge(run_id="test-run", thread_id="test-thread")
+
+    # Agent says something then calls a tool
+    text_content = TextContent(text="Let me check the weather for you.")
+    tool_call = FunctionCallContent(
+        call_id="weather-456",
+        name="get_forecast",
+        arguments={"location": "San Francisco", "days": 3},
+    )
+
+    update = AgentRunResponseUpdate(contents=[text_content, tool_call])
+    events = await bridge.from_agent_run_update(update)
+
+    # Should have: TextMessageStart, TextMessageContent, ToolCallStart, ToolCallArgs
+    assert len(events) == 4
+
+    assert isinstance(events[0], TextMessageStartEvent)
+    assert isinstance(events[1], TextMessageContentEvent)
+    assert isinstance(events[2], ToolCallStartEvent)
+    assert isinstance(events[3], ToolCallArgsEvent)
+
+    text_event = events[1]
+    assert "check the weather" in text_event.delta
+
+    tool_start = events[2]
+    assert tool_start.tool_call_name == "get_forecast"
+
+
+async def test_multiple_tool_results():
+    """Test handling multiple tool results in sequence."""
+    bridge = AgentFrameworkEventBridge(run_id="test-run", thread_id="test-thread")
+
+    # Multiple tool results
+    results = [
+        FunctionResultContent(call_id="tool-1", result="Result 1"),
+        FunctionResultContent(call_id="tool-2", result="Result 2"),
+        FunctionResultContent(call_id="tool-3", result="Result 3"),
+    ]
+
+    update = AgentRunResponseUpdate(contents=results)
+    events = await bridge.from_agent_run_update(update)
+
+    # Should have 3 pairs of ToolCallEndEvent + ToolCallResultEvent = 6 events
+    assert len(events) == 6
+
+    # Verify the pattern: End, Result, End, Result, End, Result
+    for i in range(3):
+        end_idx = i * 2
+        result_idx = i * 2 + 1
+
+        assert isinstance(events[end_idx], ToolCallEndEvent)
+        assert isinstance(events[result_idx], ToolCallResultEvent)
+
+        assert events[end_idx].tool_call_id == f"tool-{i + 1}"
+        assert events[result_idx].tool_call_id == f"tool-{i + 1}"
+        assert f"Result {i + 1}" in events[result_idx].content

python/packages/ag-ui/tests/test_confirmation_strategies_comprehensive.py

@@ -0,0 +1,275 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Comprehensive tests for all confirmation strategies."""
+
+import pytest
+
+from agent_framework_ag_ui._confirmation_strategies import (
+    ConfirmationStrategy,
+    DefaultConfirmationStrategy,
+    DocumentWriterConfirmationStrategy,
+    RecipeConfirmationStrategy,
+    TaskPlannerConfirmationStrategy,
+)
+
+
+@pytest.fixture
+def sample_steps():
+    """Sample steps for testing approval messages."""
+    return [
+        {"description": "Step 1: Do something", "status": "enabled"},
+        {"description": "Step 2: Do another thing", "status": "enabled"},
+        {"description": "Step 3: Disabled step", "status": "disabled"},
+    ]
+
+
+@pytest.fixture
+def all_enabled_steps():
+    """All steps enabled."""
+    return [
+        {"description": "Task A", "status": "enabled"},
+        {"description": "Task B", "status": "enabled"},
+        {"description": "Task C", "status": "enabled"},
+    ]
+
+
+@pytest.fixture
+def empty_steps():
+    """Empty steps list."""
+    return []
+
+
+class TestDefaultConfirmationStrategy:
+    """Tests for DefaultConfirmationStrategy."""
+
+    def test_on_approval_accepted_with_enabled_steps(self, sample_steps):
+        strategy = DefaultConfirmationStrategy()
+        message = strategy.on_approval_accepted(sample_steps)
+
+        assert "Executing 2 approved steps" in message
+        assert "Step 1: Do something" in message
+        assert "Step 2: Do another thing" in message
+        assert "Step 3" not in message  # Disabled step shouldn't appear
+        assert "All steps completed successfully!" in message
+
+    def test_on_approval_accepted_with_all_enabled(self, all_enabled_steps):
+        strategy = DefaultConfirmationStrategy()
+        message = strategy.on_approval_accepted(all_enabled_steps)
+
+        assert "Executing 3 approved steps" in message
+        assert "Task A" in message
+        assert "Task B" in message
+        assert "Task C" in message
+
+    def test_on_approval_accepted_with_empty_steps(self, empty_steps):
+        strategy = DefaultConfirmationStrategy()
+        message = strategy.on_approval_accepted(empty_steps)
+
+        assert "Executing 0 approved steps" in message
+        assert "All steps completed successfully!" in message
+
+    def test_on_approval_rejected(self, sample_steps):
+        strategy = DefaultConfirmationStrategy()
+        message = strategy.on_approval_rejected(sample_steps)
+
+        assert "No problem!" in message
+        assert "What would you like me to change" in message
+
+    def test_on_state_confirmed(self):
+        strategy = DefaultConfirmationStrategy()
+        message = strategy.on_state_confirmed()
+
+        assert "Changes confirmed" in message
+        assert "successfully" in message
+
+    def test_on_state_rejected(self):
+        strategy = DefaultConfirmationStrategy()
+        message = strategy.on_state_rejected()
+
+        assert "No problem!" in message
+        assert "What would you like me to change" in message
+
+
+class TestTaskPlannerConfirmationStrategy:
+    """Tests for TaskPlannerConfirmationStrategy."""
+
+    def test_on_approval_accepted_with_enabled_steps(self, sample_steps):
+        strategy = TaskPlannerConfirmationStrategy()
+        message = strategy.on_approval_accepted(sample_steps)
+
+        assert "Executing your requested tasks" in message
+        assert "1. Step 1: Do something" in message
+        assert "2. Step 2: Do another thing" in message
+        assert "Step 3" not in message
+        assert "All tasks completed successfully!" in message
+
+    def test_on_approval_accepted_with_all_enabled(self, all_enabled_steps):
+        strategy = TaskPlannerConfirmationStrategy()
+        message = strategy.on_approval_accepted(all_enabled_steps)
+
+        assert "Executing your requested tasks" in message
+        assert "1. Task A" in message
+        assert "2. Task B" in message
+        assert "3. Task C" in message
+
+    def test_on_approval_accepted_with_empty_steps(self, empty_steps):
+        strategy = TaskPlannerConfirmationStrategy()
+        message = strategy.on_approval_accepted(empty_steps)
+
+        assert "Executing your requested tasks" in message
+        assert "All tasks completed successfully!" in message
+
+    def test_on_approval_rejected(self, sample_steps):
+        strategy = TaskPlannerConfirmationStrategy()
+        message = strategy.on_approval_rejected(sample_steps)
+
+        assert "No problem!" in message
+        assert "revise the plan" in message
+
+    def test_on_state_confirmed(self):
+        strategy = TaskPlannerConfirmationStrategy()
+        message = strategy.on_state_confirmed()
+
+        assert "Tasks confirmed" in message
+        assert "ready to execute" in message
+
+    def test_on_state_rejected(self):
+        strategy = TaskPlannerConfirmationStrategy()
+        message = strategy.on_state_rejected()
+
+        assert "No problem!" in message
+        assert "adjust the task list" in message
+
+
+class TestRecipeConfirmationStrategy:
+    """Tests for RecipeConfirmationStrategy."""
+
+    def test_on_approval_accepted_with_enabled_steps(self, sample_steps):
+        strategy = RecipeConfirmationStrategy()
+        message = strategy.on_approval_accepted(sample_steps)
+
+        assert "Updating your recipe" in message
+        assert "1. Step 1: Do something" in message
+        assert "2. Step 2: Do another thing" in message
+        assert "Step 3" not in message
+        assert "Recipe updated successfully!" in message
+
+    def test_on_approval_accepted_with_all_enabled(self, all_enabled_steps):
+        strategy = RecipeConfirmationStrategy()
+        message = strategy.on_approval_accepted(all_enabled_steps)
+
+        assert "Updating your recipe" in message
+        assert "1. Task A" in message
+        assert "2. Task B" in message
+        assert "3. Task C" in message
+
+    def test_on_approval_accepted_with_empty_steps(self, empty_steps):
+        strategy = RecipeConfirmationStrategy()
+        message = strategy.on_approval_accepted(empty_steps)
+
+        assert "Updating your recipe" in message
+        assert "Recipe updated successfully!" in message
+
+    def test_on_approval_rejected(self, sample_steps):
+        strategy = RecipeConfirmationStrategy()
+        message = strategy.on_approval_rejected(sample_steps)
+
+        assert "No problem!" in message
+        assert "ingredients or steps" in message
+
+    def test_on_state_confirmed(self):
+        strategy = RecipeConfirmationStrategy()
+        message = strategy.on_state_confirmed()
+
+        assert "Recipe changes applied" in message
+        assert "successfully" in message
+
+    def test_on_state_rejected(self):
+        strategy = RecipeConfirmationStrategy()
+        message = strategy.on_state_rejected()
+
+        assert "No problem!" in message
+        assert "adjust in the recipe" in message
+
+
+class TestDocumentWriterConfirmationStrategy:
+    """Tests for DocumentWriterConfirmationStrategy."""
+
+    def test_on_approval_accepted_with_enabled_steps(self, sample_steps):
+        strategy = DocumentWriterConfirmationStrategy()
+        message = strategy.on_approval_accepted(sample_steps)
+
+        assert "Applying your edits" in message
+        assert "1. Step 1: Do something" in message
+        assert "2. Step 2: Do another thing" in message
+        assert "Step 3" not in message
+        assert "Document updated successfully!" in message
+
+    def test_on_approval_accepted_with_all_enabled(self, all_enabled_steps):
+        strategy = DocumentWriterConfirmationStrategy()
+        message = strategy.on_approval_accepted(all_enabled_steps)
+
+        assert "Applying your edits" in message
+        assert "1. Task A" in message
+        assert "2. Task B" in message
+        assert "3. Task C" in message
+
+    def test_on_approval_accepted_with_empty_steps(self, empty_steps):
+        strategy = DocumentWriterConfirmationStrategy()
+        message = strategy.on_approval_accepted(empty_steps)
+
+        assert "Applying your edits" in message
+        assert "Document updated successfully!" in message
+
+    def test_on_approval_rejected(self, sample_steps):
+        strategy = DocumentWriterConfirmationStrategy()
+        message = strategy.on_approval_rejected(sample_steps)
+
+        assert "No problem!" in message
+        assert "keep or modify" in message
+
+    def test_on_state_confirmed(self):
+        strategy = DocumentWriterConfirmationStrategy()
+        message = strategy.on_state_confirmed()
+
+        assert "Document edits applied!" in message
+
+    def test_on_state_rejected(self):
+        strategy = DocumentWriterConfirmationStrategy()
+        message = strategy.on_state_rejected()
+
+        assert "No problem!" in message
+        assert "change about the document" in message
+
+
+class TestConfirmationStrategyInterface:
+    """Tests for ConfirmationStrategy abstract base class."""
+
+    def test_cannot_instantiate_abstract_class(self):
+        """Verify ConfirmationStrategy is abstract and cannot be instantiated."""
+        with pytest.raises(TypeError):
+            ConfirmationStrategy()  # type: ignore
+
+    def test_all_strategies_implement_interface(self):
+        """Verify all concrete strategies implement the full interface."""
+        strategies = [
+            DefaultConfirmationStrategy(),
+            TaskPlannerConfirmationStrategy(),
+            RecipeConfirmationStrategy(),
+            DocumentWriterConfirmationStrategy(),
+        ]
+
+        sample_steps = [{"description": "Test", "status": "enabled"}]
+
+        for strategy in strategies:
+            # All should have these methods
+            assert callable(strategy.on_approval_accepted)
+            assert callable(strategy.on_approval_rejected)
+            assert callable(strategy.on_state_confirmed)
+            assert callable(strategy.on_state_rejected)
+
+            # All should return strings
+            assert isinstance(strategy.on_approval_accepted(sample_steps), str)
+            assert isinstance(strategy.on_approval_rejected(sample_steps), str)
+            assert isinstance(strategy.on_state_confirmed(), str)
+            assert isinstance(strategy.on_state_rejected(), str)

python/packages/ag-ui/tests/test_document_writer_flow.py

@@ -0,0 +1,243 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for document writer predictive state flow with confirm_changes."""
+
+from ag_ui.core import EventType
+from agent_framework import FunctionCallContent, FunctionResultContent, TextContent
+from agent_framework._types import AgentRunResponseUpdate
+
+from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+
+async def test_streaming_document_with_state_deltas():
+    """Test that streaming tool arguments emit progressive StateDeltaEvents."""
+    predict_config = {
+        "document": {"tool": "write_document_local", "tool_argument": "document"},
+    }
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config=predict_config,
+    )
+
+    # Simulate streaming tool call - first chunk with name
+    tool_call_start = FunctionCallContent(
+        call_id="call_123",
+        name="write_document_local",
+        arguments='{"document":"Once',
+    )
+    update1 = AgentRunResponseUpdate(contents=[tool_call_start])
+    events1 = await bridge.from_agent_run_update(update1)
+
+    # Should have ToolCallStartEvent and ToolCallArgsEvent
+    assert any(e.type == EventType.TOOL_CALL_START for e in events1)
+    assert any(e.type == EventType.TOOL_CALL_ARGS for e in events1)
+
+    # Second chunk - incomplete JSON, should try partial extraction
+    tool_call_chunk2 = FunctionCallContent(
+        call_id="call_123",
+        name=None,  # Name only in first chunk
+        arguments=" upon a time",
+    )
+    update2 = AgentRunResponseUpdate(contents=[tool_call_chunk2])
+    events2 = await bridge.from_agent_run_update(update2)
+
+    # Should emit StateDeltaEvent with partial document
+    state_deltas = [e for e in events2 if e.type == EventType.STATE_DELTA]
+    assert len(state_deltas) >= 1
+
+    # Check JSON Patch format
+    delta = state_deltas[0]
+    assert isinstance(delta.delta, list)
+    assert len(delta.delta) > 0
+    assert delta.delta[0]["op"] == "replace"
+    assert delta.delta[0]["path"] == "/document"
+    assert "Once upon a time" in delta.delta[0]["value"]
+
+
+async def test_confirm_changes_emission():
+    """Test that confirm_changes tool call is emitted after predictive tool completion."""
+    predict_config = {
+        "document": {"tool": "write_document_local", "tool_argument": "document"},
+    }
+
+    current_state = {}
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config=predict_config,
+        current_state=current_state,
+    )
+
+    # Set current tool name (simulating earlier tool call start)
+    bridge.current_tool_call_name = "write_document_local"
+    bridge.pending_state_updates = {"document": "A short story"}
+
+    # Tool result
+    tool_result = FunctionResultContent(
+        call_id="call_123",
+        result="Document written.",
+    )
+
+    update = AgentRunResponseUpdate(contents=[tool_result])
+    events = await bridge.from_agent_run_update(update)
+
+    # Should have: ToolCallEndEvent, ToolCallResultEvent, StateSnapshotEvent, confirm_changes sequence
+    assert any(e.type == EventType.TOOL_CALL_END for e in events)
+    assert any(e.type == EventType.TOOL_CALL_RESULT for e in events)
+    assert any(e.type == EventType.STATE_SNAPSHOT for e in events)
+
+    # Check for confirm_changes tool call
+    confirm_starts = [
+        e for e in events if e.type == EventType.TOOL_CALL_START and e.tool_call_name == "confirm_changes"
+    ]
+    assert len(confirm_starts) == 1
+
+    confirm_args = [e for e in events if e.type == EventType.TOOL_CALL_ARGS and e.delta == "{}"]
+    assert len(confirm_args) >= 1
+
+    confirm_ends = [e for e in events if e.type == EventType.TOOL_CALL_END]
+    # At least 2: one for write_document_local, one for confirm_changes
+    assert len(confirm_ends) >= 2
+
+    # Check that stop flag is set
+    assert bridge.should_stop_after_confirm is True
+
+
+async def test_text_suppression_before_confirm():
+    """Test that text messages are suppressed when confirm_changes is pending."""
+    predict_config = {
+        "document": {"tool": "write_document_local", "tool_argument": "document"},
+    }
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config=predict_config,
+    )
+
+    # Set flag indicating we're waiting for confirmation
+    bridge.should_stop_after_confirm = True
+
+    # Text content that should be suppressed
+    text = TextContent(text="I have written a story about pirates.")
+    update = AgentRunResponseUpdate(contents=[text])
+
+    events = await bridge.from_agent_run_update(update)
+
+    # Should NOT emit TextMessageContentEvent
+    text_events = [e for e in events if e.type == EventType.TEXT_MESSAGE_CONTENT]
+    assert len(text_events) == 0
+
+    # But should save the text
+    assert bridge.suppressed_summary == "I have written a story about pirates."
+
+
+async def test_no_confirm_for_non_predictive_tools():
+    """Test that confirm_changes is NOT emitted for regular tool calls."""
+    predict_config = {
+        "document": {"tool": "write_document_local", "tool_argument": "document"},
+    }
+
+    current_state = {}
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config=predict_config,
+        current_state=current_state,
+    )
+
+    # Different tool (not in predict_state_config)
+    bridge.current_tool_call_name = "get_weather"
+
+    tool_result = FunctionResultContent(
+        call_id="call_456",
+        result="Sunny, 72°F",
+    )
+
+    update = AgentRunResponseUpdate(contents=[tool_result])
+    events = await bridge.from_agent_run_update(update)
+
+    # Should NOT have confirm_changes
+    confirm_starts = [
+        e for e in events if e.type == EventType.TOOL_CALL_START and e.tool_call_name == "confirm_changes"
+    ]
+    assert len(confirm_starts) == 0
+
+    # Stop flag should NOT be set
+    assert bridge.should_stop_after_confirm is False
+
+
+async def test_state_delta_deduplication():
+    """Test that duplicate state values don't emit multiple StateDeltaEvents."""
+    predict_config = {
+        "document": {"tool": "write_document_local", "tool_argument": "document"},
+    }
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config=predict_config,
+    )
+
+    # First tool call with document
+    tool_call1 = FunctionCallContent(
+        call_id="call_1",
+        name="write_document_local",
+        arguments='{"document":"Same text"}',
+    )
+    update1 = AgentRunResponseUpdate(contents=[tool_call1])
+    events1 = await bridge.from_agent_run_update(update1)
+
+    # Count state deltas
+    state_deltas_1 = [e for e in events1 if e.type == EventType.STATE_DELTA]
+    assert len(state_deltas_1) >= 1
+
+    # Second tool call with SAME document (shouldn't emit new delta)
+    bridge.current_tool_call_name = "write_document_local"
+    tool_call2 = FunctionCallContent(
+        call_id="call_2",
+        name=None,
+        arguments='{"document":"Same text"}',  # Identical content
+    )
+    update2 = AgentRunResponseUpdate(contents=[tool_call2])
+    events2 = await bridge.from_agent_run_update(update2)
+
+    # Should NOT emit state delta (same value)
+    state_deltas_2 = [e for e in events2 if e.type == EventType.STATE_DELTA]
+    assert len(state_deltas_2) == 0
+
+
+async def test_predict_state_config_multiple_fields():
+    """Test predictive state with multiple state fields."""
+    predict_config = {
+        "title": {"tool": "create_post", "tool_argument": "title"},
+        "content": {"tool": "create_post", "tool_argument": "body"},
+    }
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config=predict_config,
+    )
+
+    # Tool call with both fields
+    tool_call = FunctionCallContent(
+        call_id="call_999",
+        name="create_post",
+        arguments='{"title":"My Post","body":"Post content"}',
+    )
+    update = AgentRunResponseUpdate(contents=[tool_call])
+    events = await bridge.from_agent_run_update(update)
+
+    # Should emit StateDeltaEvent for both fields
+    state_deltas = [e for e in events if e.type == EventType.STATE_DELTA]
+    assert len(state_deltas) >= 2
+
+    # Check both fields are present
+    paths = [delta.delta[0]["path"] for delta in state_deltas]
+    assert "/title" in paths
+    assert "/content" in paths

python/packages/ag-ui/tests/test_endpoint.py

@@ -0,0 +1,242 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for FastAPI endpoint creation (_endpoint.py)."""
+
+import json
+from typing import Any
+
+from agent_framework import ChatAgent, TextContent
+from agent_framework._types import ChatResponseUpdate
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from agent_framework_ag_ui._agent import AgentFrameworkAgent
+from agent_framework_ag_ui._endpoint import add_agent_framework_fastapi_endpoint
+
+
+class MockChatClient:
+    """Mock chat client for testing."""
+
+    def __init__(self, response_text: str = "Test response"):
+        self.response_text = response_text
+
+    async def get_streaming_response(self, messages: list[Any], chat_options: Any, **kwargs: Any):
+        """Mock streaming response."""
+        yield ChatResponseUpdate(contents=[TextContent(text=self.response_text)])
+
+
+async def test_add_endpoint_with_agent_protocol():
+    """Test adding endpoint with raw AgentProtocol."""
+    app = FastAPI()
+    agent = ChatAgent(name="test", instructions="Test agent", chat_client=MockChatClient())
+
+    add_agent_framework_fastapi_endpoint(app, agent, path="/test-agent")
+
+    client = TestClient(app)
+    response = client.post("/test-agent", json={"messages": [{"role": "user", "content": "Hello"}]})
+
+    assert response.status_code == 200
+    assert response.headers["content-type"] == "text/event-stream; charset=utf-8"
+
+
+async def test_add_endpoint_with_wrapped_agent():
+    """Test adding endpoint with pre-wrapped AgentFrameworkAgent."""
+    app = FastAPI()
+    agent = ChatAgent(name="test", instructions="Test agent", chat_client=MockChatClient())
+    wrapped_agent = AgentFrameworkAgent(agent=agent, name="wrapped")
+
+    add_agent_framework_fastapi_endpoint(app, wrapped_agent, path="/wrapped-agent")
+
+    client = TestClient(app)
+    response = client.post("/wrapped-agent", json={"messages": [{"role": "user", "content": "Hello"}]})
+
+    assert response.status_code == 200
+    assert response.headers["content-type"] == "text/event-stream; charset=utf-8"
+
+
+async def test_endpoint_with_state_schema():
+    """Test endpoint with state_schema parameter."""
+    app = FastAPI()
+    agent = ChatAgent(name="test", instructions="Test agent", chat_client=MockChatClient())
+    state_schema = {"document": {"type": "string"}}
+
+    add_agent_framework_fastapi_endpoint(app, agent, path="/stateful", state_schema=state_schema)
+
+    client = TestClient(app)
+    response = client.post(
+        "/stateful", json={"messages": [{"role": "user", "content": "Hello"}], "state": {"document": ""}}
+    )
+
+    assert response.status_code == 200
+
+
+async def test_endpoint_with_predict_state_config():
+    """Test endpoint with predict_state_config parameter."""
+    app = FastAPI()
+    agent = ChatAgent(name="test", instructions="Test agent", chat_client=MockChatClient())
+    predict_config = {"document": {"tool": "write_doc", "tool_argument": "content"}}
+
+    add_agent_framework_fastapi_endpoint(app, agent, path="/predictive", predict_state_config=predict_config)
+
+    client = TestClient(app)
+    response = client.post("/predictive", json={"messages": [{"role": "user", "content": "Hello"}]})
+
+    assert response.status_code == 200
+
+
+async def test_endpoint_request_logging():
+    """Test that endpoint logs request details."""
+    app = FastAPI()
+    agent = ChatAgent(name="test", instructions="Test agent", chat_client=MockChatClient())
+
+    add_agent_framework_fastapi_endpoint(app, agent, path="/logged")
+
+    client = TestClient(app)
+    response = client.post(
+        "/logged",
+        json={
+            "messages": [{"role": "user", "content": "Test"}],
+            "run_id": "run-123",
+            "thread_id": "thread-456",
+        },
+    )
+
+    assert response.status_code == 200
+
+
+async def test_endpoint_event_streaming():
+    """Test that endpoint streams events correctly."""
+    app = FastAPI()
+    agent = ChatAgent(name="test", instructions="Test agent", chat_client=MockChatClient("Streamed response"))
+
+    add_agent_framework_fastapi_endpoint(app, agent, path="/stream")
+
+    client = TestClient(app)
+    response = client.post("/stream", json={"messages": [{"role": "user", "content": "Hello"}]})
+
+    assert response.status_code == 200
+
+    content = response.content.decode("utf-8")
+    lines = [line for line in content.split("\n") if line.strip()]
+
+    found_run_started = False
+    found_text_content = False
+    found_run_finished = False
+
+    for line in lines:
+        if line.startswith("data: "):
+            event_data = json.loads(line[6:])
+            if event_data.get("type") == "RUN_STARTED":
+                found_run_started = True
+            elif event_data.get("type") == "TEXT_MESSAGE_CONTENT":
+                found_text_content = True
+            elif event_data.get("type") == "RUN_FINISHED":
+                found_run_finished = True
+
+    assert found_run_started
+    assert found_text_content
+    assert found_run_finished
+
+
+async def test_endpoint_error_handling():
+    """Test endpoint error handling during request parsing."""
+    app = FastAPI()
+    agent = ChatAgent(name="test", instructions="Test agent", chat_client=MockChatClient())
+
+    add_agent_framework_fastapi_endpoint(app, agent, path="/failing")
+
+    client = TestClient(app)
+
+    # Send invalid JSON to trigger parsing error before streaming
+    response = client.post("/failing", data="invalid json", headers={"content-type": "application/json"})
+
+    # The exception handler catches it and returns JSON error
+    assert response.status_code == 200
+    content = json.loads(response.content)
+    assert "error" in content
+    assert "Expecting value" in content["error"]
+
+
+async def test_endpoint_multiple_paths():
+    """Test adding multiple endpoints with different paths."""
+    app = FastAPI()
+    agent1 = ChatAgent(name="agent1", instructions="First agent", chat_client=MockChatClient("Response 1"))
+    agent2 = ChatAgent(name="agent2", instructions="Second agent", chat_client=MockChatClient("Response 2"))
+
+    add_agent_framework_fastapi_endpoint(app, agent1, path="/agent1")
+    add_agent_framework_fastapi_endpoint(app, agent2, path="/agent2")
+
+    client = TestClient(app)
+
+    response1 = client.post("/agent1", json={"messages": [{"role": "user", "content": "Hi"}]})
+    response2 = client.post("/agent2", json={"messages": [{"role": "user", "content": "Hi"}]})
+
+    assert response1.status_code == 200
+    assert response2.status_code == 200
+
+
+async def test_endpoint_default_path():
+    """Test endpoint with default path."""
+    app = FastAPI()
+    agent = ChatAgent(name="test", instructions="Test agent", chat_client=MockChatClient())
+
+    add_agent_framework_fastapi_endpoint(app, agent)
+
+    client = TestClient(app)
+    response = client.post("/", json={"messages": [{"role": "user", "content": "Hello"}]})
+
+    assert response.status_code == 200
+
+
+async def test_endpoint_response_headers():
+    """Test that endpoint sets correct response headers."""
+    app = FastAPI()
+    agent = ChatAgent(name="test", instructions="Test agent", chat_client=MockChatClient())
+
+    add_agent_framework_fastapi_endpoint(app, agent, path="/headers")
+
+    client = TestClient(app)
+    response = client.post("/headers", json={"messages": [{"role": "user", "content": "Test"}]})
+
+    assert response.status_code == 200
+    assert response.headers["content-type"] == "text/event-stream; charset=utf-8"
+    assert "cache-control" in response.headers
+    assert response.headers["cache-control"] == "no-cache"
+
+
+async def test_endpoint_empty_messages():
+    """Test endpoint with empty messages list."""
+    app = FastAPI()
+    agent = ChatAgent(name="test", instructions="Test agent", chat_client=MockChatClient())
+
+    add_agent_framework_fastapi_endpoint(app, agent, path="/empty")
+
+    client = TestClient(app)
+    response = client.post("/empty", json={"messages": []})
+
+    assert response.status_code == 200
+
+
+async def test_endpoint_complex_input():
+    """Test endpoint with complex input data."""
+    app = FastAPI()
+    agent = ChatAgent(name="test", instructions="Test agent", chat_client=MockChatClient())
+
+    add_agent_framework_fastapi_endpoint(app, agent, path="/complex")
+
+    client = TestClient(app)
+    response = client.post(
+        "/complex",
+        json={
+            "messages": [
+                {"role": "user", "content": "First message", "id": "msg-1"},
+                {"role": "assistant", "content": "Response", "id": "msg-2"},
+                {"role": "user", "content": "Follow-up", "id": "msg-3"},
+            ],
+            "run_id": "complex-run-123",
+            "thread_id": "complex-thread-456",
+            "state": {"custom_field": "value"},
+        },
+    )
+
+    assert response.status_code == 200

python/packages/ag-ui/tests/test_events_comprehensive.py

@@ -0,0 +1,659 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Comprehensive tests for AgentFrameworkEventBridge (_events.py)."""
+
+import json
+
+from agent_framework import (
+    AgentRunResponseUpdate,
+    FunctionApprovalRequestContent,
+    FunctionCallContent,
+    FunctionResultContent,
+    TextContent,
+)
+
+
+async def test_basic_text_message_conversion():
+    """Test basic TextContent to AG-UI events."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    update = AgentRunResponseUpdate(contents=[TextContent(text="Hello")])
+    events = await bridge.from_agent_run_update(update)
+
+    assert len(events) == 2
+    assert events[0].type == "TEXT_MESSAGE_START"
+    assert events[0].role == "assistant"
+    assert events[1].type == "TEXT_MESSAGE_CONTENT"
+    assert events[1].delta == "Hello"
+
+
+async def test_text_message_streaming():
+    """Test streaming TextContent with multiple chunks."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    update1 = AgentRunResponseUpdate(contents=[TextContent(text="Hello ")])
+    update2 = AgentRunResponseUpdate(contents=[TextContent(text="world")])
+
+    events1 = await bridge.from_agent_run_update(update1)
+    events2 = await bridge.from_agent_run_update(update2)
+
+    # First update: START + CONTENT
+    assert len(events1) == 2
+    assert events1[0].type == "TEXT_MESSAGE_START"
+    assert events1[1].delta == "Hello "
+
+    # Second update: just CONTENT (same message)
+    assert len(events2) == 1
+    assert events2[0].type == "TEXT_MESSAGE_CONTENT"
+    assert events2[0].delta == "world"
+
+    # Both content events should have same message_id
+    assert events1[1].message_id == events2[0].message_id
+
+
+async def test_skip_text_content_for_structured_outputs():
+    """Test that text content is skipped when skip_text_content=True."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread", skip_text_content=True)
+
+    update = AgentRunResponseUpdate(contents=[TextContent(text='{"result": "data"}')])
+    events = await bridge.from_agent_run_update(update)
+
+    # No events should be emitted
+    assert len(events) == 0
+
+
+async def test_tool_call_with_name():
+    """Test FunctionCallContent with name emits ToolCallStartEvent."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    update = AgentRunResponseUpdate(contents=[FunctionCallContent(name="search_web", call_id="call_123")])
+    events = await bridge.from_agent_run_update(update)
+
+    assert len(events) == 1
+    assert events[0].type == "TOOL_CALL_START"
+    assert events[0].tool_call_name == "search_web"
+    assert events[0].tool_call_id == "call_123"
+
+
+async def test_tool_call_streaming_args():
+    """Test streaming tool call arguments."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    # First chunk: name only
+    update1 = AgentRunResponseUpdate(contents=[FunctionCallContent(name="search_web", call_id="call_123")])
+    events1 = await bridge.from_agent_run_update(update1)
+
+    # Second chunk: arguments chunk 1 (name can be empty string for continuation)
+    update2 = AgentRunResponseUpdate(
+        contents=[FunctionCallContent(name="", call_id="call_123", arguments='{"query": "')]
+    )
+    events2 = await bridge.from_agent_run_update(update2)
+
+    # Third chunk: arguments chunk 2
+    update3 = AgentRunResponseUpdate(contents=[FunctionCallContent(name="", call_id="call_123", arguments='AI"}')])
+    events3 = await bridge.from_agent_run_update(update3)
+
+    # First update: ToolCallStartEvent
+    assert len(events1) == 1
+    assert events1[0].type == "TOOL_CALL_START"
+
+    # Second update: ToolCallArgsEvent
+    assert len(events2) == 1
+    assert events2[0].type == "TOOL_CALL_ARGS"
+    assert events2[0].delta == '{"query": "'
+
+    # Third update: ToolCallArgsEvent
+    assert len(events3) == 1
+    assert events3[0].type == "TOOL_CALL_ARGS"
+    assert events3[0].delta == 'AI"}'
+
+    # All should have same tool_call_id
+    assert events1[0].tool_call_id == events2[0].tool_call_id == events3[0].tool_call_id
+
+
+async def test_tool_result_with_dict():
+    """Test FunctionResultContent with dict result."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    result_data = {"status": "success", "count": 42}
+    update = AgentRunResponseUpdate(contents=[FunctionResultContent(call_id="call_123", result=result_data)])
+    events = await bridge.from_agent_run_update(update)
+
+    # Should emit ToolCallEndEvent + ToolCallResultEvent
+    assert len(events) == 2
+    assert events[0].type == "TOOL_CALL_END"
+    assert events[0].tool_call_id == "call_123"
+
+    assert events[1].type == "TOOL_CALL_RESULT"
+    assert events[1].tool_call_id == "call_123"
+    assert events[1].role == "tool"
+    # Result should be JSON-serialized
+    assert json.loads(events[1].content) == result_data
+
+
+async def test_tool_result_with_string():
+    """Test FunctionResultContent with string result."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    update = AgentRunResponseUpdate(contents=[FunctionResultContent(call_id="call_123", result="Search complete")])
+    events = await bridge.from_agent_run_update(update)
+
+    assert len(events) == 2
+    assert events[0].type == "TOOL_CALL_END"
+    assert events[1].type == "TOOL_CALL_RESULT"
+    assert events[1].content == "Search complete"
+
+
+async def test_tool_result_with_none():
+    """Test FunctionResultContent with None result."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    update = AgentRunResponseUpdate(contents=[FunctionResultContent(call_id="call_123", result=None)])
+    events = await bridge.from_agent_run_update(update)
+
+    assert len(events) == 2
+    assert events[0].type == "TOOL_CALL_END"
+    assert events[1].type == "TOOL_CALL_RESULT"
+    assert events[1].content == ""
+
+
+async def test_multiple_tool_results_in_sequence():
+    """Test multiple tool results processed sequentially."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    update = AgentRunResponseUpdate(
+        contents=[
+            FunctionResultContent(call_id="call_1", result="Result 1"),
+            FunctionResultContent(call_id="call_2", result="Result 2"),
+        ]
+    )
+    events = await bridge.from_agent_run_update(update)
+
+    # Each result emits: ToolCallEndEvent + ToolCallResultEvent = 4 events total
+    assert len(events) == 4
+    assert events[0].tool_call_id == "call_1"
+    assert events[1].tool_call_id == "call_1"
+    assert events[2].tool_call_id == "call_2"
+    assert events[3].tool_call_id == "call_2"
+
+
+async def test_function_approval_request_basic():
+    """Test FunctionApprovalRequestContent conversion."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    func_call = FunctionCallContent(
+        call_id="call_123",
+        name="send_email",
+        arguments={"to": "user@example.com", "subject": "Test"},
+    )
+    approval = FunctionApprovalRequestContent(
+        id="approval_001",
+        function_call=func_call,
+    )
+
+    update = AgentRunResponseUpdate(contents=[approval])
+    events = await bridge.from_agent_run_update(update)
+
+    # Should emit: ToolCallEndEvent + CustomEvent
+    assert len(events) == 2
+
+    # First: ToolCallEndEvent to close the tool call
+    assert events[0].type == "TOOL_CALL_END"
+    assert events[0].tool_call_id == "call_123"
+
+    # Second: CustomEvent with approval details
+    assert events[1].type == "CUSTOM"
+    assert events[1].name == "function_approval_request"
+    assert events[1].value["id"] == "approval_001"
+    assert events[1].value["function_call"]["name"] == "send_email"
+
+
+async def test_empty_predict_state_config():
+    """Test behavior with no predictive state configuration."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config={},  # Empty config
+    )
+
+    # Tool call with arguments
+    update = AgentRunResponseUpdate(
+        contents=[
+            FunctionCallContent(name="write_doc", call_id="call_1", arguments='{"content": "test"}'),
+            FunctionResultContent(call_id="call_1", result="Done"),
+        ]
+    )
+    events = await bridge.from_agent_run_update(update)
+
+    # Should NOT emit StateDeltaEvent or confirm_changes
+    event_types = [e.type for e in events]
+    assert "STATE_DELTA" not in event_types
+    assert "STATE_SNAPSHOT" not in event_types
+
+    # Should have: ToolCallStart, ToolCallArgs, ToolCallEnd, ToolCallResult, MessagesSnapshot
+    # MessagesSnapshotEvent is emitted after tool results to track the conversation
+    assert event_types == [
+        "TOOL_CALL_START",
+        "TOOL_CALL_ARGS",
+        "TOOL_CALL_END",
+        "TOOL_CALL_RESULT",
+        "MESSAGES_SNAPSHOT",
+    ]
+
+
+async def test_tool_not_in_predict_state_config():
+    """Test tool that doesn't match any predict_state_config entry."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config={
+            "document": {"tool": "write_document", "tool_argument": "content"},
+        },
+    )
+
+    # Different tool name
+    update = AgentRunResponseUpdate(
+        contents=[
+            FunctionCallContent(name="search_web", call_id="call_1", arguments='{"query": "AI"}'),
+            FunctionResultContent(call_id="call_1", result="Results"),
+        ]
+    )
+    events = await bridge.from_agent_run_update(update)
+
+    # Should NOT emit StateDeltaEvent or confirm_changes
+    event_types = [e.type for e in events]
+    assert "STATE_DELTA" not in event_types
+    assert "STATE_SNAPSHOT" not in event_types
+
+
+async def test_state_management_tracking():
+    """Test current_state and pending_state_updates tracking."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    initial_state = {"document": ""}
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config={
+            "document": {"tool": "write_doc", "tool_argument": "content"},
+        },
+        current_state=initial_state,
+    )
+
+    # Streaming tool call
+    update1 = AgentRunResponseUpdate(
+        contents=[
+            FunctionCallContent(name="write_doc", call_id="call_1"),
+            FunctionCallContent(name="", call_id="call_1", arguments='{"content": "Hello"}'),
+        ]
+    )
+    await bridge.from_agent_run_update(update1)
+
+    # Check pending_state_updates was populated
+    assert "document" in bridge.pending_state_updates
+    assert bridge.pending_state_updates["document"] == "Hello"
+
+    # Tool result should update current_state
+    update2 = AgentRunResponseUpdate(contents=[FunctionResultContent(call_id="call_1", result="Done")])
+    await bridge.from_agent_run_update(update2)
+
+    # current_state should be updated
+    assert bridge.current_state["document"] == "Hello"
+
+    # pending_state_updates should be cleared
+    assert len(bridge.pending_state_updates) == 0
+
+
+async def test_wildcard_tool_argument():
+    """Test tool_argument='*' uses all arguments as state value."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config={
+            "recipe": {"tool": "create_recipe", "tool_argument": "*"},
+        },
+        current_state={},
+    )
+
+    # Complete tool call with dict arguments
+    update = AgentRunResponseUpdate(
+        contents=[
+            FunctionCallContent(
+                name="create_recipe",
+                call_id="call_1",
+                arguments={"title": "Pasta", "ingredients": ["pasta", "sauce"]},
+            ),
+            FunctionResultContent(call_id="call_1", result="Created"),
+        ]
+    )
+    events = await bridge.from_agent_run_update(update)
+
+    # Find StateDeltaEvent
+    delta_events = [e for e in events if e.type == "STATE_DELTA"]
+    assert len(delta_events) > 0
+
+    # Value should be the entire arguments dict
+    delta = delta_events[0].delta[0]
+    assert delta["path"] == "/recipe"
+    assert delta["value"] == {"title": "Pasta", "ingredients": ["pasta", "sauce"]}
+
+
+async def test_run_lifecycle_events():
+    """Test RunStartedEvent and RunFinishedEvent creation."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    started = bridge.create_run_started_event()
+    assert started.type == "RUN_STARTED"
+    assert started.run_id == "test_run"
+    assert started.thread_id == "test_thread"
+
+    finished = bridge.create_run_finished_event(result={"status": "complete"})
+    assert finished.type == "RUN_FINISHED"
+    assert finished.run_id == "test_run"
+    assert finished.thread_id == "test_thread"
+    assert finished.result == {"status": "complete"}
+
+
+async def test_message_lifecycle_events():
+    """Test TextMessageStartEvent and TextMessageEndEvent creation."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    start = bridge.create_message_start_event("msg_123", role="assistant")
+    assert start.type == "TEXT_MESSAGE_START"
+    assert start.message_id == "msg_123"
+    assert start.role == "assistant"
+
+    end = bridge.create_message_end_event("msg_123")
+    assert end.type == "TEXT_MESSAGE_END"
+    assert end.message_id == "msg_123"
+
+
+async def test_state_event_creation():
+    """Test StateSnapshotEvent and StateDeltaEvent creation helpers."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    # StateSnapshotEvent
+    snapshot = bridge.create_state_snapshot_event({"document": "content"})
+    assert snapshot.type == "STATE_SNAPSHOT"
+    assert snapshot.snapshot == {"document": "content"}
+
+    # StateDeltaEvent with JSON Patch
+    delta = bridge.create_state_delta_event([{"op": "replace", "path": "/document", "value": "new content"}])
+    assert delta.type == "STATE_DELTA"
+    assert len(delta.delta) == 1
+    assert delta.delta[0]["op"] == "replace"
+    assert delta.delta[0]["path"] == "/document"
+    assert delta.delta[0]["value"] == "new content"
+
+
+async def test_state_snapshot_after_tool_result():
+    """Test StateSnapshotEvent emission after tool result with pending updates."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config={
+            "document": {"tool": "write_doc", "tool_argument": "content"},
+        },
+        current_state={"document": ""},
+    )
+
+    # Tool call with streaming args
+    update1 = AgentRunResponseUpdate(
+        contents=[
+            FunctionCallContent(name="write_doc", call_id="call_1"),
+            FunctionCallContent(name="", call_id="call_1", arguments='{"content": "Test"}'),
+        ]
+    )
+    await bridge.from_agent_run_update(update1)
+
+    # Tool result should trigger StateSnapshotEvent
+    update2 = AgentRunResponseUpdate(contents=[FunctionResultContent(call_id="call_1", result="Done")])
+    events = await bridge.from_agent_run_update(update2)
+
+    # Should have: ToolCallEnd, ToolCallResult, StateSnapshot, ToolCallStart (confirm_changes), ToolCallArgs, ToolCallEnd
+    snapshot_events = [e for e in events if e.type == "STATE_SNAPSHOT"]
+    assert len(snapshot_events) == 1
+    assert snapshot_events[0].snapshot["document"] == "Test"
+
+
+async def test_message_id_persistence_across_chunks():
+    """Test that message_id persists across multiple text chunks."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    # First chunk
+    update1 = AgentRunResponseUpdate(contents=[TextContent(text="Hello ")])
+    events1 = await bridge.from_agent_run_update(update1)
+    message_id = events1[0].message_id
+
+    # Second chunk
+    update2 = AgentRunResponseUpdate(contents=[TextContent(text="world")])
+    events2 = await bridge.from_agent_run_update(update2)
+
+    # Should use same message_id
+    assert events2[0].message_id == message_id
+    assert bridge.current_message_id == message_id
+
+
+async def test_tool_call_id_tracking():
+    """Test tool_call_id tracking across streaming chunks."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    # First chunk with name
+    update1 = AgentRunResponseUpdate(contents=[FunctionCallContent(name="search", call_id="call_1")])
+    await bridge.from_agent_run_update(update1)
+
+    assert bridge.current_tool_call_id == "call_1"
+    assert bridge.current_tool_call_name == "search"
+
+    # Second chunk with args but no name
+    update2 = AgentRunResponseUpdate(contents=[FunctionCallContent(name="", call_id="call_1", arguments='{"q":"AI"}')])
+    events2 = await bridge.from_agent_run_update(update2)
+
+    # Should still track same tool call
+    assert bridge.current_tool_call_id == "call_1"
+    assert events2[0].tool_call_id == "call_1"
+
+
+async def test_tool_name_reset_after_result():
+    """Test current_tool_call_name is reset after tool result."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config={
+            "document": {"tool": "write_doc", "tool_argument": "content"},
+        },
+    )
+
+    # Tool call
+    update1 = AgentRunResponseUpdate(
+        contents=[
+            FunctionCallContent(name="write_doc", call_id="call_1"),
+            FunctionCallContent(name="", call_id="call_1", arguments='{"content": "Test"}'),
+        ]
+    )
+    await bridge.from_agent_run_update(update1)
+
+    assert bridge.current_tool_call_name == "write_doc"
+
+    # Tool result with predictive state (should trigger confirm_changes and reset)
+    update2 = AgentRunResponseUpdate(contents=[FunctionResultContent(call_id="call_1", result="Done")])
+    await bridge.from_agent_run_update(update2)
+
+    # Tool name should be reset
+    assert bridge.current_tool_call_name is None
+
+
+async def test_function_approval_with_wildcard_argument():
+    """Test function approval with wildcard * argument."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config={
+            "payload": {"tool": "submit", "tool_argument": "*"},
+        },
+    )
+
+    approval_content = FunctionApprovalRequestContent(
+        id="approval_1",
+        function_call=FunctionCallContent(
+            name="submit", call_id="call_1", arguments='{"key1": "value1", "key2": "value2"}'
+        ),
+    )
+
+    update = AgentRunResponseUpdate(contents=[approval_content])
+    events = await bridge.from_agent_run_update(update)
+
+    # Should emit StateSnapshotEvent with entire parsed args as value
+    snapshot_events = [e for e in events if e.type == "STATE_SNAPSHOT"]
+    assert len(snapshot_events) == 1
+    assert snapshot_events[0].snapshot["payload"] == {"key1": "value1", "key2": "value2"}
+
+
+async def test_function_approval_missing_argument():
+    """Test function approval when specified argument is not in parsed args."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config={
+            "data": {"tool": "process", "tool_argument": "missing_field"},
+        },
+    )
+
+    approval_content = FunctionApprovalRequestContent(
+        id="approval_1",
+        function_call=FunctionCallContent(name="process", call_id="call_1", arguments='{"other_field": "value"}'),
+    )
+
+    update = AgentRunResponseUpdate(contents=[approval_content])
+    events = await bridge.from_agent_run_update(update)
+
+    # Should not emit StateSnapshotEvent since argument not found
+    snapshot_events = [e for e in events if e.type == "STATE_SNAPSHOT"]
+    assert len(snapshot_events) == 0
+
+
+async def test_empty_predict_state_config_no_deltas():
+    """Test with empty predict_state_config (no predictive updates)."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread", predict_state_config={})
+
+    # Tool call with arguments
+    update = AgentRunResponseUpdate(
+        contents=[
+            FunctionCallContent(name="search", call_id="call_1"),
+            FunctionCallContent(name="", call_id="call_1", arguments='{"query": "test"}'),
+        ]
+    )
+    events = await bridge.from_agent_run_update(update)
+
+    # Should not emit any StateDeltaEvents
+    delta_events = [e for e in events if e.type == "STATE_DELTA"]
+    assert len(delta_events) == 0
+
+
+async def test_tool_with_no_matching_config():
+    """Test tool call for tool not in predict_state_config."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config={"document": {"tool": "write_doc", "tool_argument": "content"}},
+    )
+
+    # Tool call for different tool
+    update = AgentRunResponseUpdate(
+        contents=[
+            FunctionCallContent(name="search_web", call_id="call_1"),
+            FunctionCallContent(name="", call_id="call_1", arguments='{"query": "test"}'),
+        ]
+    )
+    events = await bridge.from_agent_run_update(update)
+
+    # Should not emit StateDeltaEvents
+    delta_events = [e for e in events if e.type == "STATE_DELTA"]
+    assert len(delta_events) == 0
+
+
+async def test_tool_call_without_name_or_id():
+    """Test handling FunctionCallContent with no name and no call_id."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(run_id="test_run", thread_id="test_thread")
+
+    # This should not crash but log an error
+    update = AgentRunResponseUpdate(contents=[FunctionCallContent(name="", call_id="", arguments='{"arg": "val"}')])
+    events = await bridge.from_agent_run_update(update)
+
+    # Should emit ToolCallArgsEvent with generated ID
+    assert len(events) >= 1
+
+
+async def test_state_delta_count_logging():
+    """Test that state delta count increments and logs at intervals."""
+    from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+        predict_state_config={"doc": {"tool": "write", "tool_argument": "text"}},
+    )
+
+    # Emit multiple state deltas with different content each time
+    for i in range(15):
+        update = AgentRunResponseUpdate(
+            contents=[
+                FunctionCallContent(name="", call_id="call_1", arguments=f'{{"text": "Content variation {i}"}}'),
+            ]
+        )
+        # Set the tool name to match config
+        bridge.current_tool_call_name = "write"
+        await bridge.from_agent_run_update(update)
+
+    # State delta count should have incremented (one per unique state update)
+    assert bridge.state_delta_count >= 1

python/packages/ag-ui/tests/test_human_in_the_loop.py

@@ -0,0 +1,96 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for human in the loop (function approval requests)."""
+
+from agent_framework import FunctionApprovalRequestContent, FunctionCallContent
+from agent_framework._types import AgentRunResponseUpdate
+
+from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+
+async def test_function_approval_request_emission():
+    """Test that CustomEvent is emitted for FunctionApprovalRequestContent."""
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+    )
+
+    # Create approval request
+    func_call = FunctionCallContent(
+        call_id="call_123",
+        name="send_email",
+        arguments={"to": "user@example.com", "subject": "Test"},
+    )
+    approval_request = FunctionApprovalRequestContent(
+        id="approval_001",
+        function_call=func_call,
+    )
+
+    update = AgentRunResponseUpdate(contents=[approval_request])
+    events = await bridge.from_agent_run_update(update)
+
+    # Should emit ToolCallEndEvent + CustomEvent for approval request
+    assert len(events) == 2
+
+    # First event: ToolCallEndEvent to close the tool call
+    assert events[0].type == "TOOL_CALL_END"
+    assert events[0].tool_call_id == "call_123"
+
+    # Second event: CustomEvent with approval details
+    event = events[1]
+    assert event.type == "CUSTOM"
+    assert event.name == "function_approval_request"
+    assert event.value["id"] == "approval_001"
+    assert event.value["function_call"]["call_id"] == "call_123"
+    assert event.value["function_call"]["name"] == "send_email"
+    assert event.value["function_call"]["arguments"]["to"] == "user@example.com"
+    assert event.value["function_call"]["arguments"]["subject"] == "Test"
+
+
+async def test_multiple_approval_requests():
+    """Test handling multiple approval requests in one update."""
+    bridge = AgentFrameworkEventBridge(
+        run_id="test_run",
+        thread_id="test_thread",
+    )
+
+    func_call_1 = FunctionCallContent(
+        call_id="call_1",
+        name="create_event",
+        arguments={"title": "Meeting"},
+    )
+    approval_1 = FunctionApprovalRequestContent(
+        id="approval_1",
+        function_call=func_call_1,
+    )
+
+    func_call_2 = FunctionCallContent(
+        call_id="call_2",
+        name="book_room",
+        arguments={"room": "Conference A"},
+    )
+    approval_2 = FunctionApprovalRequestContent(
+        id="approval_2",
+        function_call=func_call_2,
+    )
+
+    update = AgentRunResponseUpdate(contents=[approval_1, approval_2])
+    events = await bridge.from_agent_run_update(update)
+
+    # Should emit ToolCallEndEvent + CustomEvent for each approval (4 events total)
+    assert len(events) == 4
+
+    # Events should alternate: End, Custom, End, Custom
+    assert events[0].type == "TOOL_CALL_END"
+    assert events[0].tool_call_id == "call_1"
+
+    assert events[1].type == "CUSTOM"
+    assert events[1].name == "function_approval_request"
+    assert events[1].value["id"] == "approval_1"
+
+    assert events[2].type == "TOOL_CALL_END"
+    assert events[2].tool_call_id == "call_2"
+
+    assert events[3].type == "CUSTOM"
+    assert events[3].name == "function_approval_request"
+    assert events[3].value["id"] == "approval_2"

python/packages/ag-ui/tests/test_message_adapters.py

@@ -0,0 +1,249 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for message adapters."""
+
+import pytest
+from agent_framework import ChatMessage, FunctionCallContent, Role, TextContent
+
+from agent_framework_ag_ui._message_adapters import (
+    agent_framework_messages_to_agui,
+    agui_messages_to_agent_framework,
+    extract_text_from_contents,
+)
+
+
+@pytest.fixture
+def sample_agui_message():
+    """Create a sample AG-UI message."""
+    return {"role": "user", "content": "Hello", "id": "msg-123"}
+
+
+@pytest.fixture
+def sample_agent_framework_message():
+    """Create a sample Agent Framework message."""
+    return ChatMessage(role=Role.USER, contents=[TextContent(text="Hello")], message_id="msg-123")
+
+
+def test_agui_to_agent_framework_basic(sample_agui_message):
+    """Test converting AG-UI message to Agent Framework."""
+    messages = agui_messages_to_agent_framework([sample_agui_message])
+
+    assert len(messages) == 1
+    assert messages[0].role == Role.USER
+    assert messages[0].message_id == "msg-123"
+
+
+def test_agent_framework_to_agui_basic(sample_agent_framework_message):
+    """Test converting Agent Framework message to AG-UI."""
+    messages = agent_framework_messages_to_agui([sample_agent_framework_message])
+
+    assert len(messages) == 1
+    assert messages[0]["role"] == "user"
+    assert messages[0]["content"] == "Hello"
+    assert messages[0]["id"] == "msg-123"
+
+
+def test_agui_tool_result_to_agent_framework():
+    """Test converting AG-UI tool result message to Agent Framework."""
+    tool_result_message = {
+        "role": "tool",
+        "content": '{"accepted": true, "steps": []}',
+        "toolCallId": "call_123",
+        "id": "msg_456",
+    }
+
+    messages = agui_messages_to_agent_framework([tool_result_message])
+
+    assert len(messages) == 1
+    message = messages[0]
+
+    assert message.role == Role.USER
+
+    assert len(message.contents) == 1
+    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"
+
+
+def test_agui_multiple_messages_to_agent_framework():
+    """Test converting multiple AG-UI messages."""
+    messages_input = [
+        {"role": "user", "content": "First message", "id": "msg-1"},
+        {"role": "assistant", "content": "Second message", "id": "msg-2"},
+        {"role": "user", "content": "Third message", "id": "msg-3"},
+    ]
+
+    messages = agui_messages_to_agent_framework(messages_input)
+
+    assert len(messages) == 3
+    assert messages[0].role == Role.USER
+    assert messages[1].role == Role.ASSISTANT
+    assert messages[2].role == Role.USER
+
+
+def test_agui_empty_messages():
+    """Test handling of empty messages list."""
+    messages = agui_messages_to_agent_framework([])
+    assert len(messages) == 0
+
+
+def test_agui_function_approvals():
+    """Test converting function approvals from AG-UI to Agent Framework."""
+    agui_msg = {
+        "role": "user",
+        "function_approvals": [
+            {
+                "call_id": "call-1",
+                "name": "search",
+                "arguments": {"query": "test"},
+                "approved": True,
+                "id": "approval-1",
+            },
+            {
+                "call_id": "call-2",
+                "name": "update",
+                "arguments": {"value": 42},
+                "approved": False,
+                "id": "approval-2",
+            },
+        ],
+        "id": "msg-123",
+    }
+
+    messages = agui_messages_to_agent_framework([agui_msg])
+
+    assert len(messages) == 1
+    msg = messages[0]
+    assert msg.role == Role.USER
+    assert len(msg.contents) == 2
+
+    from agent_framework import FunctionApprovalResponseContent
+
+    assert isinstance(msg.contents[0], FunctionApprovalResponseContent)
+    assert msg.contents[0].approved is True
+    assert msg.contents[0].id == "approval-1"
+    assert msg.contents[0].function_call.name == "search"
+    assert msg.contents[0].function_call.call_id == "call-1"
+
+    assert isinstance(msg.contents[1], FunctionApprovalResponseContent)
+    assert msg.contents[1].approved is False
+
+
+def test_agui_system_role():
+    """Test converting system role messages."""
+    messages = agui_messages_to_agent_framework([{"role": "system", "content": "System prompt"}])
+
+    assert len(messages) == 1
+    assert messages[0].role == Role.SYSTEM
+
+
+def test_agui_non_string_content():
+    """Test handling non-string content."""
+    messages = agui_messages_to_agent_framework([{"role": "user", "content": {"nested": "object"}}])
+
+    assert len(messages) == 1
+    assert len(messages[0].contents) == 1
+    assert isinstance(messages[0].contents[0], TextContent)
+    assert "nested" in messages[0].contents[0].text
+
+
+def test_agui_message_without_id():
+    """Test message without ID field."""
+    messages = agui_messages_to_agent_framework([{"role": "user", "content": "No ID"}])
+
+    assert len(messages) == 1
+    assert messages[0].message_id is None
+
+
+def test_agent_framework_to_agui_with_tool_calls():
+    """Test converting Agent Framework message with tool calls to AG-UI."""
+    msg = ChatMessage(
+        role=Role.ASSISTANT,
+        contents=[
+            TextContent(text="Calling tool"),
+            FunctionCallContent(call_id="call-123", name="search", arguments={"query": "test"}),
+        ],
+        message_id="msg-456",
+    )
+
+    messages = agent_framework_messages_to_agui([msg])
+
+    assert len(messages) == 1
+    agui_msg = messages[0]
+    assert agui_msg["role"] == "assistant"
+    assert agui_msg["content"] == "Calling tool"
+    assert "tool_calls" in agui_msg
+    assert len(agui_msg["tool_calls"]) == 1
+    assert agui_msg["tool_calls"][0]["id"] == "call-123"
+    assert agui_msg["tool_calls"][0]["type"] == "function"
+    assert agui_msg["tool_calls"][0]["function"]["name"] == "search"
+    assert agui_msg["tool_calls"][0]["function"]["arguments"] == {"query": "test"}
+
+
+def test_agent_framework_to_agui_multiple_text_contents():
+    """Test concatenating multiple text contents."""
+    msg = ChatMessage(
+        role=Role.ASSISTANT,
+        contents=[TextContent(text="Part 1 "), TextContent(text="Part 2")],
+    )
+
+    messages = agent_framework_messages_to_agui([msg])
+
+    assert len(messages) == 1
+    assert messages[0]["content"] == "Part 1 Part 2"
+
+
+def test_agent_framework_to_agui_no_message_id():
+    """Test message without message_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]
+
+
+def test_agent_framework_to_agui_system_role():
+    """Test system role conversion."""
+    msg = ChatMessage(role=Role.SYSTEM, contents=[TextContent(text="System")])
+
+    messages = agent_framework_messages_to_agui([msg])
+
+    assert len(messages) == 1
+    assert messages[0]["role"] == "system"
+
+
+def test_extract_text_from_contents():
+    """Test extracting text from contents list."""
+    contents = [TextContent(text="Hello "), TextContent(text="World")]
+
+    result = extract_text_from_contents(contents)
+
+    assert result == "Hello World"
+
+
+def test_extract_text_from_empty_contents():
+    """Test extracting text from empty contents."""
+    result = extract_text_from_contents([])
+
+    assert result == ""
+
+
+class CustomTextContent:
+    """Custom content with text attribute."""
+
+    def __init__(self, text: str):
+        self.text = text
+
+
+def test_extract_text_from_custom_contents():
+    """Test extracting text from custom content objects."""
+    contents = [CustomTextContent(text="Custom "), TextContent(text="Mixed")]
+
+    result = extract_text_from_contents(contents)
+
+    assert result == "Custom Mixed"

python/packages/ag-ui/tests/test_shared_state.py

@@ -0,0 +1,109 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for shared state management."""
+
+import pytest
+from ag_ui.core import StateSnapshotEvent
+from agent_framework import ChatAgent, TextContent
+from agent_framework._types import ChatResponseUpdate
+
+from agent_framework_ag_ui._agent import AgentFrameworkAgent
+from agent_framework_ag_ui._events import AgentFrameworkEventBridge
+
+
+@pytest.fixture
+def mock_agent():
+    """Create a mock agent for testing."""
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Hello!")])
+
+    return ChatAgent(
+        name="test_agent",
+        instructions="Test agent",
+        chat_client=MockChatClient(),
+    )
+
+
+def test_state_snapshot_event():
+    """Test creating state snapshot events."""
+    bridge = AgentFrameworkEventBridge(run_id="test-run", thread_id="test-thread")
+
+    state = {
+        "recipe": {
+            "name": "Chocolate Chip Cookies",
+            "ingredients": ["flour", "sugar", "chocolate chips"],
+            "instructions": ["Mix ingredients", "Bake at 350°F"],
+            "servings": 24,
+        }
+    }
+
+    event = bridge.create_state_snapshot_event(state)
+
+    assert isinstance(event, StateSnapshotEvent)
+    assert event.snapshot == state
+    assert event.snapshot["recipe"]["name"] == "Chocolate Chip Cookies"
+    assert len(event.snapshot["recipe"]["ingredients"]) == 3
+
+
+def test_state_delta_event():
+    """Test creating state delta events using JSON Patch format."""
+    bridge = AgentFrameworkEventBridge(run_id="test-run", thread_id="test-thread")
+
+    # JSON Patch operations (RFC 6902)
+    delta = [
+        {"op": "add", "path": "/recipe/ingredients/-", "value": "vanilla extract"},
+        {"op": "replace", "path": "/recipe/servings", "value": 30},
+    ]
+
+    event = bridge.create_state_delta_event(delta)
+
+    assert event.delta == delta
+    assert len(event.delta) == 2
+    assert event.delta[0]["op"] == "add"
+    assert event.delta[1]["op"] == "replace"
+
+
+async def test_agent_with_initial_state(mock_agent):
+    """Test agent emits state snapshot when initial state provided."""
+    state_schema = {"recipe": {"type": "object", "properties": {"name": {"type": "string"}}}}
+
+    agent = AgentFrameworkAgent(
+        agent=mock_agent,
+        state_schema=state_schema,
+    )
+
+    initial_state = {"recipe": {"name": "Test Recipe"}}
+
+    input_data = {
+        "messages": [{"role": "user", "content": "Hello"}],
+        "state": initial_state,
+    }
+
+    events = []
+    async for event in agent.run_agent(input_data):
+        events.append(event)
+
+    # Should have RunStartedEvent, StateSnapshotEvent, RunFinishedEvent at minimum
+    snapshot_events = [e for e in events if isinstance(e, StateSnapshotEvent)]
+    assert len(snapshot_events) == 1
+    assert snapshot_events[0].snapshot == initial_state
+
+
+async def test_agent_without_state_schema(mock_agent):
+    """Test agent doesn't emit state events without state schema."""
+    agent = AgentFrameworkAgent(agent=mock_agent)
+
+    input_data = {
+        "messages": [{"role": "user", "content": "Hello"}],
+        "state": {"some": "state"},
+    }
+
+    events = []
+    async for event in agent.run_agent(input_data):
+        events.append(event)
+
+    # Should NOT have any StateSnapshotEvent
+    snapshot_events = [e for e in events if isinstance(e, StateSnapshotEvent)]
+    assert len(snapshot_events) == 0

python/packages/ag-ui/tests/test_structured_output.py

@@ -0,0 +1,257 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for structured output handling in _agent.py."""
+
+import json
+from typing import Any
+
+from agent_framework import ChatAgent, ChatOptions, TextContent
+from agent_framework._types import ChatResponseUpdate
+from pydantic import BaseModel
+
+
+class RecipeOutput(BaseModel):
+    """Test Pydantic model for recipe output."""
+
+    recipe: dict[str, Any]
+    message: str | None = None
+
+
+class StepsOutput(BaseModel):
+    """Test Pydantic model for steps output."""
+
+    steps: list[dict[str, Any]]
+    message: str | None = None
+
+
+class GenericOutput(BaseModel):
+    """Test Pydantic model for generic data."""
+
+    data: dict[str, Any]
+
+
+async def test_structured_output_with_recipe():
+    """Test structured output processing with recipe state."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            # Simulate structured output
+            yield ChatResponseUpdate(
+                contents=[TextContent(text='{"recipe": {"name": "Pasta"}, "message": "Here is your recipe"}')]
+            )
+
+    agent = ChatAgent(name="test", instructions="Test", chat_client=MockChatClient())
+    agent.chat_options = ChatOptions(response_format=RecipeOutput)
+
+    wrapper = AgentFrameworkAgent(
+        agent=agent,
+        state_schema={"recipe": {"type": "object"}},
+    )
+
+    input_data = {"messages": [{"role": "user", "content": "Make pasta"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should emit StateSnapshotEvent with recipe
+    snapshot_events = [e for e in events if e.type == "STATE_SNAPSHOT"]
+    assert len(snapshot_events) >= 1
+    # Find snapshot with recipe
+    recipe_snapshots = [e for e in snapshot_events if "recipe" in e.snapshot]
+    assert len(recipe_snapshots) >= 1
+    assert recipe_snapshots[0].snapshot["recipe"] == {"name": "Pasta"}
+
+    # Should also emit message as text
+    text_events = [e for e in events if e.type == "TEXT_MESSAGE_CONTENT"]
+    assert any("Here is your recipe" in e.delta for e in text_events)
+
+
+async def test_structured_output_with_steps():
+    """Test structured output processing with steps state."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            steps_data = {
+                "steps": [
+                    {"id": "1", "description": "Step 1", "status": "pending"},
+                    {"id": "2", "description": "Step 2", "status": "pending"},
+                ]
+            }
+            yield ChatResponseUpdate(contents=[TextContent(text=json.dumps(steps_data))])
+
+    agent = ChatAgent(name="test", instructions="Test", chat_client=MockChatClient())
+    agent.chat_options = ChatOptions(response_format=StepsOutput)
+
+    wrapper = AgentFrameworkAgent(
+        agent=agent,
+        state_schema={"steps": {"type": "array"}},
+    )
+
+    input_data = {"messages": [{"role": "user", "content": "Do steps"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should emit StateSnapshotEvent with steps
+    snapshot_events = [e for e in events if e.type == "STATE_SNAPSHOT"]
+    assert len(snapshot_events) >= 1
+
+    # Snapshot should contain steps
+    steps_snapshots = [e for e in snapshot_events if "steps" in e.snapshot]
+    assert len(steps_snapshots) >= 1
+    assert len(steps_snapshots[0].snapshot["steps"]) == 2
+    assert steps_snapshots[0].snapshot["steps"][0]["id"] == "1"
+
+
+async def test_structured_output_with_no_schema_match():
+    """Test structured output when response fields don't match state_schema keys."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            # Response has "data" field but schema expects "result" field
+            yield ChatResponseUpdate(contents=[TextContent(text='{"data": {"key": "value"}}')])
+
+    agent = ChatAgent(name="test", instructions="Test", chat_client=MockChatClient())
+    agent.chat_options = ChatOptions(response_format=GenericOutput)
+
+    wrapper = AgentFrameworkAgent(
+        agent=agent,
+        state_schema={"result": {"type": "object"}},  # Schema expects "result", not "data"
+    )
+
+    input_data = {"messages": [{"role": "user", "content": "Generate data"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should emit StateSnapshotEvent but with no state updates since no schema fields match
+    snapshot_events = [e for e in events if e.type == "STATE_SNAPSHOT"]
+    # Initial state snapshot from state_schema initialization
+    assert len(snapshot_events) >= 1
+
+
+async def test_structured_output_without_schema():
+    """Test structured output without state_schema treats all fields as state."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class DataOutput(BaseModel):
+        """Output with data and info fields."""
+
+        data: dict[str, Any]
+        info: str
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text='{"data": {"key": "value"}, "info": "processed"}')])
+
+    agent = ChatAgent(name="test", instructions="Test", chat_client=MockChatClient())
+    agent.chat_options = ChatOptions(response_format=DataOutput)
+
+    wrapper = AgentFrameworkAgent(
+        agent=agent,
+        # No state_schema - all non-message fields treated as state
+    )
+
+    input_data = {"messages": [{"role": "user", "content": "Generate data"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should emit StateSnapshotEvent with both data and info fields
+    snapshot_events = [e for e in events if e.type == "STATE_SNAPSHOT"]
+    assert len(snapshot_events) >= 1
+    assert "data" in snapshot_events[0].snapshot
+    assert "info" in snapshot_events[0].snapshot
+    assert snapshot_events[0].snapshot["data"] == {"key": "value"}
+    assert snapshot_events[0].snapshot["info"] == "processed"
+
+
+async def test_no_structured_output_when_no_response_format():
+    """Test that structured output path is skipped when no response_format."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            yield ChatResponseUpdate(contents=[TextContent(text="Regular text")])
+
+    agent = ChatAgent(name="test", instructions="Test", chat_client=MockChatClient())
+    # No response_format set
+
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    input_data = {"messages": [{"role": "user", "content": "Hi"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should emit text content normally
+    text_events = [e for e in events if e.type == "TEXT_MESSAGE_CONTENT"]
+    assert len(text_events) > 0
+    assert text_events[0].delta == "Regular text"
+
+
+async def test_structured_output_with_message_field():
+    """Test structured output that includes a message field."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            output_data = {"recipe": {"name": "Salad"}, "message": "Fresh salad recipe ready"}
+            yield ChatResponseUpdate(contents=[TextContent(text=json.dumps(output_data))])
+
+    agent = ChatAgent(name="test", instructions="Test", chat_client=MockChatClient())
+    agent.chat_options = ChatOptions(response_format=RecipeOutput)
+
+    wrapper = AgentFrameworkAgent(
+        agent=agent,
+        state_schema={"recipe": {"type": "object"}},
+    )
+
+    input_data = {"messages": [{"role": "user", "content": "Make salad"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should emit the message as text
+    text_events = [e for e in events if e.type == "TEXT_MESSAGE_CONTENT"]
+    assert any("Fresh salad recipe ready" in e.delta for e in text_events)
+
+    # Should also have TextMessageStart and TextMessageEnd
+    start_events = [e for e in events if e.type == "TEXT_MESSAGE_START"]
+    end_events = [e for e in events if e.type == "TEXT_MESSAGE_END"]
+    assert len(start_events) >= 1
+    assert len(end_events) >= 1
+
+
+async def test_empty_updates_no_structured_processing():
+    """Test that empty updates don't trigger structured output processing."""
+    from agent_framework_ag_ui import AgentFrameworkAgent
+
+    class MockChatClient:
+        async def get_streaming_response(self, messages, chat_options, **kwargs):
+            # Return nothing
+            if False:
+                yield
+
+    agent = ChatAgent(name="test", instructions="Test", chat_client=MockChatClient())
+    agent.chat_options = ChatOptions(response_format=RecipeOutput)
+
+    wrapper = AgentFrameworkAgent(agent=agent)
+
+    input_data = {"messages": [{"role": "user", "content": "Test"}]}
+
+    events = []
+    async for event in wrapper.run_agent(input_data):
+        events.append(event)
+
+    # Should only have start and end events
+    assert len(events) == 2  # RunStarted, RunFinished

python/packages/ag-ui/tests/test_types.py

@@ -0,0 +1,145 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for type definitions in _types.py."""
+
+from agent_framework_ag_ui._types import AgentState, PredictStateConfig, RunMetadata
+
+
+class TestPredictStateConfig:
+    """Test PredictStateConfig TypedDict."""
+
+    def test_predict_state_config_creation(self) -> None:
+        """Test creating a PredictStateConfig dict."""
+        config: PredictStateConfig = {
+            "state_key": "document",
+            "tool": "write_document",
+            "tool_argument": "content",
+        }
+
+        assert config["state_key"] == "document"
+        assert config["tool"] == "write_document"
+        assert config["tool_argument"] == "content"
+
+    def test_predict_state_config_with_none_tool_argument(self) -> None:
+        """Test PredictStateConfig with None tool_argument."""
+        config: PredictStateConfig = {
+            "state_key": "status",
+            "tool": "update_status",
+            "tool_argument": None,
+        }
+
+        assert config["state_key"] == "status"
+        assert config["tool"] == "update_status"
+        assert config["tool_argument"] is None
+
+    def test_predict_state_config_type_validation(self) -> None:
+        """Test that PredictStateConfig validates field types at runtime."""
+        config: PredictStateConfig = {
+            "state_key": "test",
+            "tool": "test_tool",
+            "tool_argument": "arg",
+        }
+
+        assert isinstance(config["state_key"], str)
+        assert isinstance(config["tool"], str)
+        assert isinstance(config["tool_argument"], (str, type(None)))
+
+
+class TestRunMetadata:
+    """Test RunMetadata TypedDict."""
+
+    def test_run_metadata_creation(self) -> None:
+        """Test creating a RunMetadata dict."""
+        metadata: RunMetadata = {
+            "run_id": "run-123",
+            "thread_id": "thread-456",
+            "predict_state": [
+                {
+                    "state_key": "document",
+                    "tool": "write_document",
+                    "tool_argument": "content",
+                }
+            ],
+        }
+
+        assert metadata["run_id"] == "run-123"
+        assert metadata["thread_id"] == "thread-456"
+        assert metadata["predict_state"] is not None
+        assert len(metadata["predict_state"]) == 1
+        assert metadata["predict_state"][0]["state_key"] == "document"
+
+    def test_run_metadata_with_none_predict_state(self) -> None:
+        """Test RunMetadata with None predict_state."""
+        metadata: RunMetadata = {
+            "run_id": "run-789",
+            "thread_id": "thread-012",
+            "predict_state": None,
+        }
+
+        assert metadata["run_id"] == "run-789"
+        assert metadata["thread_id"] == "thread-012"
+        assert metadata["predict_state"] is None
+
+    def test_run_metadata_empty_predict_state(self) -> None:
+        """Test RunMetadata with empty predict_state list."""
+        metadata: RunMetadata = {
+            "run_id": "run-345",
+            "thread_id": "thread-678",
+            "predict_state": [],
+        }
+
+        assert metadata["run_id"] == "run-345"
+        assert metadata["thread_id"] == "thread-678"
+        assert metadata["predict_state"] == []
+
+
+class TestAgentState:
+    """Test AgentState TypedDict."""
+
+    def test_agent_state_creation(self) -> None:
+        """Test creating an AgentState dict."""
+        state: AgentState = {
+            "messages": [
+                {"role": "user", "content": "Hello"},
+                {"role": "assistant", "content": "Hi there"},
+            ]
+        }
+
+        assert state["messages"] is not None
+        assert len(state["messages"]) == 2
+        assert state["messages"][0]["role"] == "user"
+        assert state["messages"][1]["role"] == "assistant"
+
+    def test_agent_state_with_none_messages(self) -> None:
+        """Test AgentState with None messages."""
+        state: AgentState = {"messages": None}
+
+        assert state["messages"] is None
+
+    def test_agent_state_empty_messages(self) -> None:
+        """Test AgentState with empty messages list."""
+        state: AgentState = {"messages": []}
+
+        assert state["messages"] == []
+
+    def test_agent_state_complex_messages(self) -> None:
+        """Test AgentState with complex message structures."""
+        state: AgentState = {
+            "messages": [
+                {
+                    "role": "user",
+                    "content": "Test",
+                    "metadata": {"timestamp": "2025-10-30"},
+                },
+                {
+                    "role": "assistant",
+                    "content": "Response",
+                    "tool_calls": [{"name": "search", "args": {}}],
+                },
+            ]
+        }
+
+        assert state["messages"] is not None
+        assert len(state["messages"]) == 2
+        assert "metadata" in state["messages"][0]
+        assert "tool_calls" in state["messages"][1]

python/packages/ag-ui/tests/test_utils.py

@@ -0,0 +1,199 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for utilities."""
+
+from dataclasses import dataclass
+from datetime import date, datetime
+
+from agent_framework_ag_ui._utils import generate_event_id, make_json_safe, merge_state
+
+
+def test_generate_event_id():
+    """Test event ID generation."""
+    id1 = generate_event_id()
+    id2 = generate_event_id()
+
+    assert id1 != id2
+    assert isinstance(id1, str)
+    assert len(id1) > 0
+
+
+def test_merge_state():
+    """Test state merging."""
+    current = {"a": 1, "b": 2}
+    update = {"b": 3, "c": 4}
+
+    result = merge_state(current, update)
+
+    assert result["a"] == 1
+    assert result["b"] == 3
+    assert result["c"] == 4
+
+
+def test_merge_state_empty_update():
+    """Test merging with empty update."""
+    current = {"x": 10, "y": 20}
+    update = {}
+
+    result = merge_state(current, update)
+
+    assert result == current
+    assert result is not current
+
+
+def test_merge_state_empty_current():
+    """Test merging with empty current state."""
+    current = {}
+    update = {"a": 1, "b": 2}
+
+    result = merge_state(current, update)
+
+    assert result == update
+
+
+def test_merge_state_deep_copy():
+    """Test that merge_state creates a deep copy preventing mutation of original."""
+    current = {"recipe": {"name": "Cake", "ingredients": ["flour", "sugar"]}}
+    update = {"other": "value"}
+
+    result = merge_state(current, update)
+
+    result["recipe"]["ingredients"].append("eggs")
+
+    assert "eggs" not in current["recipe"]["ingredients"]
+    assert current["recipe"]["ingredients"] == ["flour", "sugar"]
+    assert result["recipe"]["ingredients"] == ["flour", "sugar", "eggs"]
+
+
+def test_make_json_safe_basic():
+    """Test JSON serialization of basic types."""
+    assert make_json_safe("text") == "text"
+    assert make_json_safe(123) == 123
+    assert make_json_safe(None) is None
+    assert make_json_safe(3.14) == 3.14
+    assert make_json_safe(True) is True
+    assert make_json_safe(False) is False
+
+
+def test_make_json_safe_datetime():
+    """Test datetime serialization."""
+    dt = datetime(2025, 10, 30, 12, 30, 45)
+    result = make_json_safe(dt)
+    assert result == "2025-10-30T12:30:45"
+
+
+def test_make_json_safe_date():
+    """Test date serialization."""
+    d = date(2025, 10, 30)
+    result = make_json_safe(d)
+    assert result == "2025-10-30"
+
+
+@dataclass
+class SampleDataclass:
+    """Sample dataclass for testing."""
+
+    name: str
+    value: int
+
+
+def test_make_json_safe_dataclass():
+    """Test dataclass serialization."""
+    obj = SampleDataclass(name="test", value=42)
+    result = make_json_safe(obj)
+    assert result == {"name": "test", "value": 42}
+
+
+class ModelDumpObject:
+    """Object with model_dump method."""
+
+    def model_dump(self):
+        return {"type": "model", "data": "dump"}
+
+
+def test_make_json_safe_model_dump():
+    """Test object with model_dump method."""
+    obj = ModelDumpObject()
+    result = make_json_safe(obj)
+    assert result == {"type": "model", "data": "dump"}
+
+
+class DictObject:
+    """Object with dict method."""
+
+    def dict(self):
+        return {"type": "dict", "method": "call"}
+
+
+def test_make_json_safe_dict_method():
+    """Test object with dict method."""
+    obj = DictObject()
+    result = make_json_safe(obj)
+    assert result == {"type": "dict", "method": "call"}
+
+
+class CustomObject:
+    """Custom object with __dict__."""
+
+    def __init__(self):
+        self.field1 = "value1"
+        self.field2 = 123
+
+
+def test_make_json_safe_dict_attribute():
+    """Test object with __dict__ attribute."""
+    obj = CustomObject()
+    result = make_json_safe(obj)
+    assert result == {"field1": "value1", "field2": 123}
+
+
+def test_make_json_safe_list():
+    """Test list serialization."""
+    lst = [1, "text", None, {"key": "value"}]
+    result = make_json_safe(lst)
+    assert result == [1, "text", None, {"key": "value"}]
+
+
+def test_make_json_safe_tuple():
+    """Test tuple serialization."""
+    tpl = (1, 2, 3)
+    result = make_json_safe(tpl)
+    assert result == [1, 2, 3]
+
+
+def test_make_json_safe_dict():
+    """Test dict serialization."""
+    d = {"a": 1, "b": {"c": 2}}
+    result = make_json_safe(d)
+    assert result == {"a": 1, "b": {"c": 2}}
+
+
+def test_make_json_safe_nested():
+    """Test nested structure serialization."""
+    obj = {
+        "datetime": datetime(2025, 10, 30),
+        "list": [1, 2, CustomObject()],
+        "nested": {"value": SampleDataclass(name="nested", value=99)},
+    }
+    result = make_json_safe(obj)
+
+    assert result["datetime"] == "2025-10-30T00:00:00"
+    assert result["list"][0] == 1
+    assert result["list"][2] == {"field1": "value1", "field2": 123}
+    assert result["nested"]["value"] == {"name": "nested", "value": 99}
+
+
+class UnserializableObject:
+    """Object that can't be serialized by standard methods."""
+
+    def __init__(self):
+        # Add attribute to trigger __dict__ fallback path
+        pass
+
+
+def test_make_json_safe_fallback():
+    """Test fallback to dict for objects with __dict__."""
+    obj = UnserializableObject()
+    result = make_json_safe(obj)
+    # Objects with __dict__ return their __dict__ dict
+    assert isinstance(result, dict)

python/packages/anthropic/pyproject.toml

@@ -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.0b251028"
+version = "1.0.0b251104"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/azure-ai/pyproject.toml

@@ -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.0b251028"
+version = "1.0.0b251104"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/chatkit/.gitignore

@@ -0,0 +1,3 @@
+chatkit-python
+openai-chatkit-advanced-samples
+chatkit-js

python/packages/chatkit/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python/packages/chatkit/README.md

@@ -0,0 +1,87 @@
+# Agent Framework and ChatKit Integration
+
+This package provides an integration layer between Microsoft Agent Framework
+and [OpenAI ChatKit (Python)](https://github.com/openai/chatkit-python/).
+Specifically, it mirrors the [Agent SDK integration](https://github.com/openai/chatkit-python/blob/main/docs/server.md#agents-sdk-integration), and provides the following helpers:
+
+- `stream_agent_response`: A helper to convert a streamed `AgentRunResponseUpdate`
+  from a Microsoft Agent Framework agent that implements `AgentProtocol` to ChatKit events.
+- `ThreadItemConverter`: A extendable helper class to convert ChatKit thread items to
+  `ChatMessage` objects that can be consumed by an Agent Framework agent.
+- `simple_to_agent_input`: A helper function that uses the default implementation
+  of `ThreadItemConverter` to convert a ChatKit thread to a list of `ChatMessage`,
+  useful for getting started quickly.
+
+## Installation
+
+```bash
+pip install agent-framework-chatkit --pre
+```
+
+This will install `agent-framework-core` and `openai-chatkit` as dependencies.
+
+## Example Usage
+
+Here's a minimal example showing how to integrate Agent Framework with ChatKit:
+
+```python
+from collections.abc import AsyncIterator
+from typing import Any
+
+from azure.identity import AzureCliCredential
+from fastapi import FastAPI, Request
+from fastapi.responses import Response, StreamingResponse
+
+from agent_framework import ChatAgent
+from agent_framework.azure import AzureOpenAIChatClient
+from agent_framework.chatkit import simple_to_agent_input, stream_agent_response
+
+from chatkit.server import ChatKitServer
+from chatkit.types import ThreadMetadata, UserMessageItem, ThreadStreamEvent
+
+# You'll need to implement a Store - see the sample for a SQLiteStore implementation
+from your_store import YourStore  # type: ignore[import-not-found]  # Replace with your Store implementation
+
+# Define your agent with tools
+agent = ChatAgent(
+    chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+    instructions="You are a helpful assistant.",
+    tools=[],  # Add your tools here
+)
+
+# Create a ChatKit server that uses your agent
+class MyChatKitServer(ChatKitServer[dict[str, Any]]):
+    async def respond(
+        self,
+        thread: ThreadMetadata,
+        input_user_message: UserMessageItem | None,
+        context: dict[str, Any],
+    ) -> AsyncIterator[ThreadStreamEvent]:
+        if input_user_message is None:
+            return
+
+        # Convert ChatKit message to Agent Framework format
+        agent_messages = await simple_to_agent_input(input_user_message)
+
+        # Run the agent and stream responses
+        response_stream = agent.run_stream(agent_messages)
+
+        # Convert agent responses back to ChatKit events
+        async for event in stream_agent_response(response_stream, thread.id):
+            yield event
+
+# Set up FastAPI endpoint
+app = FastAPI()
+chatkit_server = MyChatKitServer(YourStore())  # type: ignore[misc]
+
+@app.post("/chatkit")
+async def chatkit_endpoint(request: Request):
+    result = await chatkit_server.process(await request.body(), {"request": request})
+
+    if hasattr(result, '__aiter__'):  # Streaming
+        return StreamingResponse(result, media_type="text/event-stream")  # type: ignore[arg-type]
+    else:  # Non-streaming
+        return Response(content=result.json, media_type="application/json")  # type: ignore[union-attr]
+```
+
+For a complete end-to-end example with a full frontend, see the [weather agent sample](../../samples/demos/chatkit-integration/README.md).

python/packages/chatkit/agent_framework_chatkit/__init__.py

@@ -0,0 +1,25 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Agent Framework and ChatKit Integration.
+
+This package provides an integration layer between Microsoft Agent Framework
+and OpenAI ChatKit (Python). It mirrors the Agent SDK integration and provides
+helpers to convert between Agent Framework and ChatKit types.
+"""
+
+import importlib.metadata
+
+from ._converter import ThreadItemConverter, simple_to_agent_input
+from ._streaming import stream_agent_response
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"  # Fallback for development mode
+
+__all__ = [
+    "ThreadItemConverter",
+    "__version__",
+    "simple_to_agent_input",
+    "stream_agent_response",
+]

python/packages/chatkit/agent_framework_chatkit/_converter.py

@@ -0,0 +1,603 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Converter utilities for converting ChatKit thread items to Agent Framework messages."""
+
+import logging
+import sys
+from collections.abc import Awaitable, Callable, Sequence
+
+if sys.version_info >= (3, 11):
+    from typing import assert_never
+else:
+    from typing_extensions import assert_never
+
+from agent_framework import (
+    ChatMessage,
+    DataContent,
+    FunctionCallContent,
+    FunctionResultContent,
+    Role,
+    TextContent,
+    UriContent,
+)
+from chatkit.types import (
+    AssistantMessageItem,
+    Attachment,
+    ClientToolCallItem,
+    EndOfTurnItem,
+    HiddenContextItem,
+    ImageAttachment,
+    TaskItem,
+    ThreadItem,
+    UserMessageItem,
+    UserMessageTagContent,
+    UserMessageTextContent,
+    WidgetItem,
+    WorkflowItem,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class ThreadItemConverter:
+    """Helper class to convert ChatKit thread items to Agent Framework ChatMessage objects.
+
+    This class provides a base implementation for converting ChatKit thread items
+    to Agent Framework messages. It can be extended to handle attachments,
+    @-mentions, hidden context items, and custom thread item formats.
+
+    Args:
+        attachment_data_fetcher: Optional async function to fetch attachment binary data.
+            If provided, it should take an attachment ID and return the binary data as bytes.
+            If not provided, attachments will be converted to UriContent using available URLs.
+    """
+
+    def __init__(
+        self,
+        attachment_data_fetcher: Callable[[str], Awaitable[bytes]] | None = None,
+    ) -> None:
+        """Initialize the converter.
+
+        Args:
+            attachment_data_fetcher: Optional async function to fetch attachment data by ID.
+        """
+        self.attachment_data_fetcher = attachment_data_fetcher
+
+    async def user_message_to_input(
+        self, item: UserMessageItem, is_last_message: bool = True
+    ) -> ChatMessage | list[ChatMessage] | None:
+        """Convert a ChatKit UserMessageItem to Agent Framework ChatMessage(s).
+
+        This method is called internally by `to_agent_input()`. Override this method
+        to customize how user messages are converted.
+
+        Args:
+            item: The ChatKit user message item to convert.
+            is_last_message: Whether this is the last message in the thread (used for quoted_text handling).
+
+        Returns:
+            A ChatMessage, list of messages, or None to skip.
+
+        Note:
+            Instead of calling this method directly, use `to_agent_input()` which handles
+            all ThreadItem types and provides proper message ordering.
+        """
+        # Extract text content from the user message
+        text_content = ""
+        if item.content:
+            for content_part in item.content:
+                if isinstance(content_part, UserMessageTextContent):
+                    text_content += content_part.text
+
+        # Convert attachments to DataContent or UriContent
+        data_contents: list[DataContent | UriContent] = []
+        if item.attachments:
+            for attachment in item.attachments:
+                content = await self.attachment_to_message_content(attachment)
+                if content is not None:
+                    data_contents.append(content)
+
+        # Create the message with text and attachments
+        if not text_content.strip() and not data_contents:
+            return None
+
+        # If only text and no attachments, use text parameter for simplicity
+        if text_content.strip() and not data_contents:
+            user_message = ChatMessage(role=Role.USER, text=text_content.strip())
+        else:
+            # Build contents list with both text and attachments
+            contents: list[TextContent | DataContent | UriContent] = []
+            if text_content.strip():
+                contents.append(TextContent(text=text_content.strip()))
+            contents.extend(data_contents)
+            user_message = ChatMessage(role=Role.USER, contents=contents)
+
+        # Handle quoted text if this is the last message
+        messages = [user_message]
+        if item.quoted_text and is_last_message:
+            quoted_context = ChatMessage(
+                role=Role.USER,
+                text=f"The user is referring to this in particular:\n{item.quoted_text}",
+            )
+            # Prepend quoted context before the main message
+            messages.insert(0, quoted_context)
+
+        return messages
+
+    async def attachment_to_message_content(self, attachment: Attachment) -> DataContent | UriContent | None:
+        """Convert a ChatKit attachment to Agent Framework content.
+
+        This method is called internally by `user_message_to_input()` to handle attachments.
+        Override this method to customize attachment handling for your storage backend.
+
+        The default implementation provides two strategies:
+        1. If an attachment_data_fetcher was provided, it fetches the binary data
+           and creates a DataContent object
+        2. Otherwise, for ImageAttachment with preview_url, it creates a UriContent object
+
+        For FileAttachment without a data fetcher, returns None (attachment is skipped).
+
+        Args:
+            attachment: The ChatKit attachment to convert (FileAttachment or ImageAttachment).
+
+        Returns:
+            DataContent if binary data is available, UriContent if only URL is available,
+            or None if the attachment cannot be converted.
+
+        Note:
+            Instead of calling this method directly, use `to_agent_input()` which handles
+            all ThreadItem types including attachments within user messages.
+
+        Examples:
+            .. code-block:: python
+
+                # With data fetcher
+                async def fetch_data(attachment_id: str) -> bytes:
+                    return await my_storage.get_file(attachment_id)
+
+
+                converter = ThreadItemConverter(attachment_data_fetcher=fetch_data)
+                messages = await converter.to_agent_input(thread_items)
+
+                # Without data fetcher (uses URLs for images)
+                converter = ThreadItemConverter()
+                messages = await converter.to_agent_input(thread_items)
+        """
+        # If we have a data fetcher, use it to get binary data
+        if self.attachment_data_fetcher is not None:
+            try:
+                data = await self.attachment_data_fetcher(attachment.id)
+                return DataContent(data=data, media_type=attachment.mime_type)
+            except Exception as e:
+                # If fetch fails, fall through to URL-based approach
+                logger.debug(f"Failed to fetch attachment data for {attachment.id}: {e}")
+
+        # For ImageAttachment, try to use preview_url
+        if isinstance(attachment, ImageAttachment) and attachment.preview_url:
+            return UriContent(uri=str(attachment.preview_url), media_type=attachment.mime_type)
+
+        # For FileAttachment without data fetcher, skip the attachment
+        # Subclasses can override this method to provide custom handling
+        return None
+
+    def hidden_context_to_input(self, item: HiddenContextItem) -> ChatMessage | list[ChatMessage] | None:
+        """Convert a ChatKit HiddenContextItem to Agent Framework ChatMessage(s).
+
+        This method is called internally by `to_agent_input()`. Override this method
+        to customize how hidden context is converted.
+
+        The default implementation wraps the hidden context in XML tags and returns
+        a system message. This allows the model to distinguish hidden context from
+        regular conversation.
+
+        Args:
+            item: The ChatKit hidden context item to convert.
+
+        Returns:
+            A ChatMessage with system role, a list of messages, or None to skip.
+
+        Note:
+            Instead of calling this method directly, use `to_agent_input()` which handles
+            all ThreadItem types and provides proper message ordering.
+
+        Examples:
+            .. code-block:: python
+
+                # Default behavior
+                converter = ThreadItemConverter()
+                hidden_item = HiddenContextItem(
+                    id="ctx_1",
+                    thread_id="thread_1",
+                    created_at=datetime.now(),
+                    content="User's email: user@example.com",
+                )
+                message = converter.hidden_context_to_input(hidden_item)
+                # Returns: ChatMessage(role=SYSTEM, text="<HIDDEN_CONTEXT>User's email: ...</HIDDEN_CONTEXT>")
+        """
+        return ChatMessage(role=Role.SYSTEM, text=f"<HIDDEN_CONTEXT>{item.content}</HIDDEN_CONTEXT>")
+
+    def tag_to_message_content(self, tag: UserMessageTagContent) -> TextContent:
+        """Convert a ChatKit tag (@-mention) to Agent Framework content.
+
+        This method is called internally by `user_message_to_input()` to handle tags.
+        Override this method to customize tag conversion for your application.
+
+        The default implementation extracts the tag's display name and wraps it in
+        XML tags to provide context to the model about the @-mention.
+
+        Args:
+            tag: The ChatKit tag content to convert.
+
+        Returns:
+            TextContent with the tag information.
+
+        Note:
+            Instead of calling this method directly, use `to_agent_input()` which handles
+            all ThreadItem types including tags within user messages.
+
+        Examples:
+            .. code-block:: python
+
+                # Default behavior
+                converter = ThreadItemConverter()
+                tag = UserMessageTagContent(
+                    type="input_tag", id="tag_1", text="john", data={"name": "John Doe"}, interactive=False
+                )
+                content = converter.tag_to_message_content(tag)
+                # Returns: TextContent(text="<TAG>Name:John Doe</TAG>")
+        """
+        name = getattr(tag.data, "name", tag.text if hasattr(tag, "text") else "unknown")
+        return TextContent(text=f"<TAG>Name:{name}</TAG>")
+
+    def task_to_input(self, item: TaskItem) -> ChatMessage | list[ChatMessage] | None:
+        """Convert a ChatKit TaskItem to Agent Framework ChatMessage(s).
+
+        This method is called internally by `to_agent_input()`. Override this method
+        to customize how tasks are converted.
+
+        The default implementation converts custom tasks with title/content into
+        a user message explaining what task was displayed to the user.
+
+        Args:
+            item: The ChatKit task item to convert.
+
+        Returns:
+            A ChatMessage, a list of messages, or None to skip the task.
+
+        Note:
+            Instead of calling this method directly, use `to_agent_input()` which handles
+            all ThreadItem types and provides proper message ordering.
+
+        Examples:
+            .. code-block:: python
+
+                # Task with both title and content
+                from chatkit.types import Task
+
+                task_item = TaskItem(
+                    id="task_1",
+                    thread_id="thread_1",
+                    created_at=datetime.now(),
+                    task=Task(type="custom", title="Data Analysis", content="Analyzed sales data"),
+                )
+                message = converter.task_to_input(task_item)
+                # Returns message explaining the task was performed
+        """
+        if item.task.type != "custom" or (not item.task.title and not item.task.content):
+            return None
+
+        title = item.task.title or ""
+        content = item.task.content or ""
+        task_text = f"{title}: {content}" if title and content else title or content
+        text = (
+            f"A message was displayed to the user that the following task was performed:\n<Task>\n{task_text}\n</Task>"
+        )
+
+        return ChatMessage(role=Role.USER, text=text)
+
+    def workflow_to_input(self, item: WorkflowItem) -> ChatMessage | list[ChatMessage] | None:
+        """Convert a ChatKit WorkflowItem to Agent Framework ChatMessage(s).
+
+        This method is called internally by `to_agent_input()`. Override this method
+        to customize how workflows are converted.
+
+        The default implementation converts each custom task in the workflow into
+        a separate user message explaining what tasks were performed.
+
+        Args:
+            item: The ChatKit workflow item to convert.
+
+        Returns:
+            A list of ChatMessages (one per task), a single message, or None to skip.
+
+        Note:
+            Instead of calling this method directly, use `to_agent_input()` which handles
+            all ThreadItem types and provides proper message ordering.
+
+        Examples:
+            .. code-block:: python
+
+                # Workflow with multiple tasks
+                from chatkit.types import Workflow, Task
+
+                workflow_item = WorkflowItem(
+                    id="wf_1",
+                    thread_id="thread_1",
+                    created_at=datetime.now(),
+                    workflow=Workflow(
+                        type="custom",
+                        tasks=[
+                            Task(type="custom", title="Step 1", content="Gathered data"),
+                            Task(type="custom", title="Step 2", content="Analyzed results"),
+                        ],
+                    ),
+                )
+                messages = converter.workflow_to_input(workflow_item)
+                # Returns list of messages for each task
+        """
+        messages: list[ChatMessage] = []
+        for task in item.workflow.tasks:
+            if task.type != "custom" or (not task.title and not task.content):
+                continue
+
+            title = task.title or ""
+            content = task.content or ""
+            task_text = f"{title}: {content}" if title and content else title or content
+            text = (
+                "A message was displayed to the user that the following task was performed:\n"
+                f"<Task>\n{task_text}\n</Task>"
+            )
+
+            messages.append(ChatMessage(role=Role.USER, text=text))
+
+        return messages if messages else None
+
+    def widget_to_input(self, item: WidgetItem) -> ChatMessage | list[ChatMessage] | None:
+        """Convert a ChatKit WidgetItem to Agent Framework ChatMessage(s).
+
+        This method is called internally by `to_agent_input()`. Override this method
+        to customize how widgets are converted.
+
+        The default implementation converts the widget to a JSON representation
+        and includes it in a user message, allowing the model to understand what
+        UI element was displayed to the user.
+
+        Args:
+            item: The ChatKit widget item to convert.
+
+        Returns:
+            A ChatMessage describing the widget, or None to skip.
+
+        Note:
+            Instead of calling this method directly, use `to_agent_input()` which handles
+            all ThreadItem types and provides proper message ordering.
+
+        Examples:
+            .. code-block:: python
+
+                # Widget item
+                from chatkit.widgets import Card, Text
+
+                widget_item = WidgetItem(
+                    id="widget_1",
+                    thread_id="thread_1",
+                    created_at=datetime.now(),
+                    widget=Card(children=[Text(value="Hello")]),
+                )
+                message = converter.widget_to_input(widget_item)
+                # Returns message with JSON representation of the widget
+        """
+        try:
+            widget_json = item.widget.model_dump_json(exclude_unset=True, exclude_none=True)
+            text = f"The following graphical UI widget (id: {item.id}) was displayed to the user:{widget_json}"
+            return ChatMessage(role=Role.USER, text=text)
+        except Exception:
+            # If JSON serialization fails, skip the widget
+            return None
+
+    async def assistant_message_to_input(self, item: AssistantMessageItem) -> ChatMessage | list[ChatMessage] | None:
+        """Convert a ChatKit AssistantMessageItem to Agent Framework ChatMessage(s).
+
+        The default implementation extracts text from all content parts and creates
+        an assistant message.
+
+        Args:
+            item: The ChatKit assistant message item to convert.
+
+        Returns:
+            A ChatMessage with assistant role, or None to skip.
+
+        Note:
+            Instead of calling this method directly, use `to_agent_input()` which handles
+            all ThreadItem types and provides proper message ordering.
+        """
+        # Extract text from all content parts
+        text_parts = [content.text for content in item.content]
+        if not text_parts:
+            return None
+
+        return ChatMessage(role=Role.ASSISTANT, text="".join(text_parts))
+
+    async def client_tool_call_to_input(self, item: ClientToolCallItem) -> ChatMessage | list[ChatMessage] | None:
+        """Convert a ChatKit ClientToolCallItem to Agent Framework ChatMessage(s).
+
+        The default implementation converts completed tool calls into function call
+        and result content.
+
+        Args:
+            item: The ChatKit client tool call item to convert.
+
+        Returns:
+            A list containing function call and result messages, or None for pending calls.
+
+        Note:
+            Instead of calling this method directly, use `to_agent_input()` which handles
+            all ThreadItem types and provides proper message ordering.
+        """
+        if item.status == "pending":
+            # Skip pending tool calls - they cannot be sent to the model
+            return None
+
+        import json
+
+        # Create function call message
+        function_call_msg = ChatMessage(
+            role=Role.ASSISTANT,
+            contents=[
+                FunctionCallContent(
+                    call_id=item.call_id,
+                    name=item.name,
+                    arguments=json.dumps(item.arguments),
+                )
+            ],
+        )
+
+        # Create function result message
+        function_result_msg = ChatMessage(
+            role=Role.TOOL,
+            contents=[
+                FunctionResultContent(
+                    call_id=item.call_id,
+                    result=json.dumps(item.output) if item.output is not None else "",
+                )
+            ],
+        )
+
+        return [function_call_msg, function_result_msg]
+
+    async def end_of_turn_to_input(self, item: EndOfTurnItem) -> ChatMessage | list[ChatMessage] | None:
+        """Convert a ChatKit EndOfTurnItem to Agent Framework ChatMessage(s).
+
+        The default implementation skips end-of-turn markers as they are only UI hints.
+
+        Args:
+            item: The ChatKit end-of-turn item to convert.
+
+        Returns:
+            None (end-of-turn items are not converted).
+
+        Note:
+            Instead of calling this method directly, use `to_agent_input()` which handles
+            all ThreadItem types and provides proper message ordering.
+        """
+        # End-of-turn is only used for UI hints - skip it
+        return None
+
+    async def _thread_item_to_input_item(
+        self,
+        item: ThreadItem,
+        is_last_message: bool = True,
+    ) -> list[ChatMessage]:
+        """Internal method to convert a single ThreadItem to ChatMessage(s).
+
+        Args:
+            item: The thread item to convert.
+            is_last_message: Whether this is the last item in the thread.
+
+        Returns:
+            A list of ChatMessage objects (may be empty).
+        """
+        match item:
+            case UserMessageItem():
+                out = await self.user_message_to_input(item, is_last_message) or []
+                return out if isinstance(out, list) else [out]
+            case AssistantMessageItem():
+                out = await self.assistant_message_to_input(item) or []
+                return out if isinstance(out, list) else [out]
+            case ClientToolCallItem():
+                out = await self.client_tool_call_to_input(item) or []
+                return out if isinstance(out, list) else [out]
+            case EndOfTurnItem():
+                out = await self.end_of_turn_to_input(item) or []
+                return out if isinstance(out, list) else [out]
+            case WidgetItem():
+                out = self.widget_to_input(item) or []
+                return out if isinstance(out, list) else [out]
+            case WorkflowItem():
+                out = self.workflow_to_input(item) or []
+                return out if isinstance(out, list) else [out]
+            case TaskItem():
+                out = self.task_to_input(item) or []
+                return out if isinstance(out, list) else [out]
+            case HiddenContextItem():
+                out = self.hidden_context_to_input(item) or []
+                return out if isinstance(out, list) else [out]
+            case _:
+                assert_never(item)
+
+    async def to_agent_input(
+        self,
+        thread_items: Sequence[ThreadItem] | ThreadItem,
+    ) -> list[ChatMessage]:
+        """Convert ChatKit thread items to Agent Framework ChatMessages.
+
+        This is the main entry point for converting ChatKit thread items. It handles
+        all ThreadItem types (UserMessageItem, AssistantMessageItem, TaskItem, etc.)
+        and calls the appropriate conversion method for each.
+
+        Args:
+            thread_items: A single ThreadItem or a sequence of ThreadItems to convert.
+
+        Returns:
+            A list of ChatMessage objects that can be sent to an Agent Framework agent.
+
+        Examples:
+            .. code-block:: python
+
+                from agent_framework_chatkit import ThreadItemConverter
+
+                converter = ThreadItemConverter()
+
+                # Convert a single thread item
+                messages = await converter.to_agent_input(user_message_item)
+
+                # Convert multiple thread items
+                messages = await converter.to_agent_input([user_message_item, assistant_message_item, task_item])
+
+                # Use with agent
+                from agent_framework import ChatAgent
+
+                agent = ChatAgent(...)
+                response = await agent.run_stream(messages)
+        """
+        thread_items = list(thread_items) if isinstance(thread_items, Sequence) else [thread_items]
+
+        output: list[ChatMessage] = []
+        for item in thread_items:
+            output.extend(
+                await self._thread_item_to_input_item(
+                    item,
+                    is_last_message=item is thread_items[-1],
+                )
+            )
+        return output
+
+
+# Default converter instance
+_DEFAULT_CONVERTER = ThreadItemConverter()
+
+
+async def simple_to_agent_input(thread_items: Sequence[ThreadItem] | ThreadItem) -> list[ChatMessage]:
+    """Helper function that uses the default ThreadItemConverter.
+
+    This function provides a quick way to get started with ChatKit integration
+    without needing to create a custom ThreadItemConverter instance.
+
+    Args:
+        thread_items: A single ThreadItem or a sequence of ThreadItems to convert.
+
+    Returns:
+        A list of ChatMessage objects that can be sent to an Agent Framework agent.
+
+    Examples:
+        .. code-block:: python
+
+            from agent_framework_chatkit import simple_to_agent_input
+
+            # Convert a single item
+            messages = await simple_to_agent_input(user_message_item)
+
+            # Convert multiple items
+            messages = await simple_to_agent_input([user_message_item, assistant_message_item, task_item])
+    """
+    return await _DEFAULT_CONVERTER.to_agent_input(thread_items)

python/packages/chatkit/agent_framework_chatkit/_streaming.py

@@ -0,0 +1,104 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Streaming utilities for converting Agent Framework responses to ChatKit events."""
+
+import uuid
+from collections.abc import AsyncIterable, AsyncIterator, Callable
+from datetime import datetime
+
+from agent_framework import AgentRunResponseUpdate, TextContent
+from chatkit.types import (
+    AssistantMessageContent,
+    AssistantMessageContentPartTextDelta,
+    AssistantMessageItem,
+    ThreadItemAddedEvent,
+    ThreadItemDoneEvent,
+    ThreadItemUpdated,
+    ThreadStreamEvent,
+)
+
+
+async def stream_agent_response(
+    response_stream: AsyncIterable[AgentRunResponseUpdate],
+    thread_id: str,
+    generate_id: Callable[[str], str] | None = None,
+) -> AsyncIterator[ThreadStreamEvent]:
+    """Convert a streamed AgentRunResponseUpdate from Agent Framework to ChatKit events.
+
+    This helper function takes a stream of AgentRunResponseUpdate objects from
+    a Microsoft Agent Framework agent and converts them to ChatKit ThreadStreamEvent
+    objects that can be consumed by the ChatKit UI.
+
+    The function supports real-time token-by-token streaming by emitting
+    ThreadItemUpdated events with AssistantMessageContentPartTextDelta for each
+    text chunk as it arrives from the agent.
+
+    Args:
+        response_stream: An async iterable of AgentRunResponseUpdate objects
+                        from an Agent Framework agent.
+        thread_id: The ChatKit thread ID for the conversation.
+        generate_id: Optional function to generate IDs for ChatKit items.
+                    If not provided, simple incremental IDs will be used.
+
+    Yields:
+        ThreadStreamEvent: ChatKit events representing the agent's response,
+                          including incremental text deltas for streaming display.
+    """
+    # Use provided ID generator or create default one
+    if generate_id is None:
+
+        def _default_id_generator(item_type: str) -> str:
+            return f"{item_type}_{uuid.uuid4().hex[:8]}"
+
+        message_id = _default_id_generator("msg")
+    else:
+        message_id = generate_id("msg")
+
+    # Track if we've started the message
+    message_started = False
+    accumulated_text = ""
+    content_index = 0
+
+    async for update in response_stream:
+        # Start the assistant message if not already started
+        if not message_started:
+            assistant_message = AssistantMessageItem(
+                id=message_id,
+                thread_id=thread_id,
+                type="assistant_message",
+                content=[],
+                created_at=datetime.now(),
+            )
+
+            yield ThreadItemAddedEvent(type="thread.item.added", item=assistant_message)
+            message_started = True
+
+        # Process the update content
+        if update.contents:
+            for content in update.contents:
+                # Handle text content - only TextContent has a text attribute
+                if isinstance(content, TextContent) and content.text is not None:
+                    # Yield incremental text delta for streaming display
+                    yield ThreadItemUpdated(
+                        type="thread.item.updated",
+                        item_id=message_id,
+                        update=AssistantMessageContentPartTextDelta(
+                            content_index=content_index,
+                            delta=content.text,
+                        ),
+                    )
+                    accumulated_text += content.text
+
+    # Finalize the message
+    if message_started:
+        final_message = AssistantMessageItem(
+            id=message_id,
+            thread_id=thread_id,
+            type="assistant_message",
+            content=[AssistantMessageContent(type="output_text", text=accumulated_text, annotations=[])]
+            if accumulated_text
+            else [],
+            created_at=datetime.now(),
+        )
+
+        yield ThreadItemDoneEvent(type="thread.item.done", item=final_message)

python/packages/chatkit/pyproject.toml

@@ -0,0 +1,89 @@
+[project]
+name = "agent-framework-chatkit"
+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.0b251001"
+license-files = ["LICENSE"]
+urls.homepage = "https://aka.ms/agent-framework"
+urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
+urls.release_notes = "https://github.com/microsoft/agent-framework/releases?q=tag%3Apython-1&expanded=true"
+urls.issues = "https://github.com/microsoft/agent-framework/issues"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+    "agent-framework-core",
+    "openai-chatkit>=1.1.0,<2.0.0",
+]
+
+[tool.uv]
+prerelease = "if-necessary-or-explicit"
+environments = [
+    "sys_platform == 'darwin'",
+    "sys_platform == 'linux'",
+    "sys_platform == 'win32'"
+]
+
+[tool.uv-dynamic-versioning]
+fallback-version = "0.0.0"
+[tool.pytest.ini_options]
+testpaths = 'tests'
+addopts = "-ra -q -r fEX"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+filterwarnings = []
+timeout = 120
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.ruff.lint]
+ignore = ["RUF029"]
+
+[tool.coverage.run]
+omit = [
+    "**/__init__.py"
+]
+
+[tool.pyright]
+extend = "../../pyproject.toml"
+exclude = ['tests', 'chatkit-python', 'openai-chatkit-advanced-samples']
+
+[tool.mypy]
+plugins = ['pydantic.mypy']
+strict = true
+python_version = "3.10"
+ignore_missing_imports = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+warn_return_any = true
+show_error_codes = true
+warn_unused_ignores = false
+disallow_incomplete_defs = true
+disallow_untyped_decorators = true
+
+[tool.bandit]
+targets = ["agent_framework_chatkit"]
+exclude_dirs = ["tests"]
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+[tool.poe.tasks]
+mypy = "mypy --config-file $POE_ROOT/pyproject.toml agent_framework_chatkit"
+test = "pytest --cov=agent_framework_chatkit --cov-report=term-missing:skip-covered tests"
+
+[build-system]
+requires = ["flit-core >= 3.11,<4.0"]
+build-backend = "flit_core.buildapi"

python/packages/chatkit/tests/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) Microsoft. All rights reserved.

python/packages/chatkit/tests/test_converter.py

@@ -0,0 +1,426 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for ChatKit to Agent Framework converter utilities."""
+
+from unittest.mock import Mock
+
+import pytest
+from agent_framework import ChatMessage, Role, TextContent
+from chatkit.types import UserMessageTextContent
+
+from agent_framework_chatkit import ThreadItemConverter, simple_to_agent_input
+
+
+class TestThreadItemConverter:
+    """Tests for ThreadItemConverter class."""
+
+    @pytest.fixture
+    def converter(self):
+        """Create a ThreadItemConverter instance for testing."""
+        return ThreadItemConverter()
+
+    async def test_to_agent_input_none(self, converter):
+        """Test converting empty list returns empty list."""
+        result = await converter.to_agent_input([])
+        assert result == []
+
+    async def test_to_agent_input_with_text(self, converter):
+        """Test converting user message with text content."""
+        from datetime import datetime
+
+        from chatkit.types import UserMessageItem
+
+        input_item = UserMessageItem(
+            id="msg_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="user_message",
+            content=[UserMessageTextContent(text="Hello, how can you help me?")],
+            attachments=[],
+            inference_options={},
+        )
+
+        result = await converter.to_agent_input(input_item)
+
+        assert len(result) == 1
+        assert isinstance(result[0], ChatMessage)
+        assert result[0].role == Role.USER
+        assert result[0].text == "Hello, how can you help me?"
+
+    async def test_to_agent_input_empty_text(self, converter):
+        """Test converting user message with empty or whitespace-only text."""
+        from datetime import datetime
+
+        from chatkit.types import UserMessageItem
+
+        input_item = UserMessageItem(
+            id="msg_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="user_message",
+            content=[UserMessageTextContent(text="   ")],
+            attachments=[],
+            inference_options={},
+        )
+
+        result = await converter.to_agent_input(input_item)
+        assert result == []
+
+    async def test_to_agent_input_no_content(self, converter):
+        """Test converting user message with no content."""
+        from datetime import datetime
+
+        from chatkit.types import UserMessageItem
+
+        input_item = UserMessageItem(
+            id="msg_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="user_message",
+            content=[],
+            attachments=[],
+            inference_options={},
+        )
+
+        result = await converter.to_agent_input(input_item)
+        assert result == []
+
+    async def test_to_agent_input_multiple_content_parts(self, converter):
+        """Test converting user message with multiple text content parts."""
+        from datetime import datetime
+
+        from chatkit.types import UserMessageItem
+
+        input_item = UserMessageItem(
+            id="msg_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="user_message",
+            content=[
+                UserMessageTextContent(text="Hello "),
+                UserMessageTextContent(text="world!"),
+            ],
+            attachments=[],
+            inference_options={},
+        )
+
+        result = await converter.to_agent_input(input_item)
+
+        assert len(result) == 1
+        assert result[0].text == "Hello world!"
+
+    def test_hidden_context_to_input(self, converter):
+        """Test converting hidden context item to ChatMessage."""
+        hidden_item = Mock()
+        hidden_item.content = "This is hidden context information"
+
+        result = converter.hidden_context_to_input(hidden_item)
+
+        assert isinstance(result, ChatMessage)
+        assert result.role == Role.SYSTEM
+        assert result.text == "<HIDDEN_CONTEXT>This is hidden context information</HIDDEN_CONTEXT>"
+
+    def test_tag_to_message_content(self, converter):
+        """Test converting tag to message content."""
+        from chatkit.types import UserMessageTagContent
+
+        tag = UserMessageTagContent(
+            type="input_tag",
+            id="tag_1",
+            text="john",
+            data={"name": "John Doe"},
+            interactive=False,
+        )
+
+        result = converter.tag_to_message_content(tag)
+        assert isinstance(result, TextContent)
+        # Since data is a dict, getattr won't work, so it will fall back to text
+        assert result.text == "<TAG>Name:john</TAG>"
+
+    def test_tag_to_message_content_no_name(self, converter):
+        """Test converting tag with no name to message content."""
+        from chatkit.types import UserMessageTagContent
+
+        tag = UserMessageTagContent(
+            type="input_tag",
+            id="tag_2",
+            text="jane",
+            data={},
+            interactive=False,
+        )
+
+        result = converter.tag_to_message_content(tag)
+        assert isinstance(result, TextContent)
+        assert result.text == "<TAG>Name:jane</TAG>"
+
+    async def test_attachment_to_message_content_file_without_fetcher(self, converter):
+        """Test that FileAttachment without data fetcher returns None."""
+        from chatkit.types import FileAttachment
+
+        attachment = FileAttachment(
+            id="file_123",
+            name="document.pdf",
+            mime_type="application/pdf",
+            type="file",
+        )
+
+        result = await converter.attachment_to_message_content(attachment)
+        assert result is None
+
+    async def test_attachment_to_message_content_image_with_preview_url(self, converter):
+        """Test that ImageAttachment with preview_url creates UriContent."""
+        from agent_framework import UriContent
+        from chatkit.types import ImageAttachment
+
+        attachment = ImageAttachment(
+            id="img_123",
+            name="photo.jpg",
+            mime_type="image/jpeg",
+            type="image",
+            preview_url="https://example.com/photo.jpg",
+        )
+
+        result = await converter.attachment_to_message_content(attachment)
+        assert isinstance(result, UriContent)
+        assert result.uri == "https://example.com/photo.jpg"
+        assert result.media_type == "image/jpeg"
+
+    async def test_attachment_to_message_content_with_data_fetcher(self):
+        """Test attachment conversion with data fetcher."""
+        from agent_framework import DataContent
+        from chatkit.types import FileAttachment
+
+        # Mock data fetcher
+        async def fetch_data(attachment_id: str) -> bytes:
+            return b"file content data"
+
+        converter = ThreadItemConverter(attachment_data_fetcher=fetch_data)
+
+        attachment = FileAttachment(
+            id="file_123",
+            name="document.pdf",
+            mime_type="application/pdf",
+            type="file",
+        )
+
+        result = await converter.attachment_to_message_content(attachment)
+        assert isinstance(result, DataContent)
+        assert result.media_type == "application/pdf"
+
+    async def test_to_agent_input_with_image_attachment(self):
+        """Test converting user message with text and image attachment."""
+        from datetime import datetime
+
+        from agent_framework import UriContent
+        from chatkit.types import ImageAttachment, UserMessageItem
+
+        attachment = ImageAttachment(
+            id="img_123",
+            name="photo.jpg",
+            mime_type="image/jpeg",
+            type="image",
+            preview_url="https://example.com/photo.jpg",
+        )
+
+        input_item = UserMessageItem(
+            id="msg_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="user_message",
+            content=[UserMessageTextContent(text="Check out this photo!")],
+            attachments=[attachment],
+            inference_options={},
+        )
+
+        converter = ThreadItemConverter()
+        result = await converter.to_agent_input(input_item)
+
+        assert len(result) == 1
+        message = result[0]
+        assert message.role == Role.USER
+        assert len(message.contents) == 2
+
+        # First content should be text
+        assert isinstance(message.contents[0], TextContent)
+        assert message.contents[0].text == "Check out this photo!"
+
+        # Second content should be UriContent for the image
+        assert isinstance(message.contents[1], UriContent)
+        assert message.contents[1].uri == "https://example.com/photo.jpg"
+        assert message.contents[1].media_type == "image/jpeg"
+
+    async def test_to_agent_input_with_file_attachment_and_fetcher(self):
+        """Test converting user message with file attachment using data fetcher."""
+        from datetime import datetime
+
+        from agent_framework import DataContent
+        from chatkit.types import FileAttachment, UserMessageItem
+
+        attachment = FileAttachment(
+            id="file_123",
+            name="report.pdf",
+            mime_type="application/pdf",
+            type="file",
+        )
+
+        input_item = UserMessageItem(
+            id="msg_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="user_message",
+            content=[UserMessageTextContent(text="Here's the document")],
+            attachments=[attachment],
+            inference_options={},
+        )
+
+        # Create converter with data fetcher
+        async def fetch_data(attachment_id: str) -> bytes:
+            return b"PDF content data"
+
+        converter = ThreadItemConverter(attachment_data_fetcher=fetch_data)
+        result = await converter.to_agent_input(input_item)
+
+        assert len(result) == 1
+        message = result[0]
+        assert len(message.contents) == 2
+
+        # First content should be text
+        assert isinstance(message.contents[0], TextContent)
+
+        # Second content should be DataContent for the file
+        assert isinstance(message.contents[1], DataContent)
+        assert message.contents[1].media_type == "application/pdf"
+
+    def test_task_to_input(self, converter):
+        """Test converting TaskItem to ChatMessage."""
+        from datetime import datetime
+
+        from chatkit.types import CustomTask, TaskItem
+
+        task_item = TaskItem(
+            id="task_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="task",
+            task=CustomTask(type="custom", title="Analysis", content="Analyzed the data"),
+        )
+
+        result = converter.task_to_input(task_item)
+        assert isinstance(result, ChatMessage)
+        assert result.role == Role.USER
+        assert "Analysis: Analyzed the data" in result.text
+        assert "<Task>" in result.text
+
+    def test_task_to_input_no_custom_task(self, converter):
+        """Test that non-custom tasks return None."""
+        from datetime import datetime
+
+        from chatkit.types import TaskItem, ThoughtTask
+
+        task_item = TaskItem(
+            id="task_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="task",
+            task=ThoughtTask(type="thought", title="Think", content="Thinking..."),
+        )
+
+        result = converter.task_to_input(task_item)
+        assert result is None
+
+    def test_workflow_to_input(self, converter):
+        """Test converting WorkflowItem to ChatMessages."""
+        from datetime import datetime
+
+        from chatkit.types import CustomTask, Workflow, WorkflowItem
+
+        workflow_item = WorkflowItem(
+            id="wf_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="workflow",
+            workflow=Workflow(
+                type="custom",
+                tasks=[
+                    CustomTask(type="custom", title="Step 1", content="First step"),
+                    CustomTask(type="custom", title="Step 2", content="Second step"),
+                ],
+            ),
+        )
+
+        result = converter.workflow_to_input(workflow_item)
+        assert isinstance(result, list)
+        assert len(result) == 2
+        assert all(isinstance(msg, ChatMessage) for msg in result)
+        assert "Step 1: First step" in result[0].text
+        assert "Step 2: Second step" in result[1].text
+
+    def test_workflow_to_input_empty(self, converter):
+        """Test that workflows with no custom tasks return None."""
+        from datetime import datetime
+
+        from chatkit.types import Workflow, WorkflowItem
+
+        workflow_item = WorkflowItem(
+            id="wf_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="workflow",
+            workflow=Workflow(type="custom", tasks=[]),
+        )
+
+        result = converter.workflow_to_input(workflow_item)
+        assert result is None
+
+    def test_widget_to_input(self, converter):
+        """Test converting WidgetItem to ChatMessage."""
+        from datetime import datetime
+
+        from chatkit.types import WidgetItem
+        from chatkit.widgets import Card, Text
+
+        widget_item = WidgetItem(
+            id="widget_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="widget",
+            widget=Card(key="card1", children=[Text(value="Hello")]),
+        )
+
+        result = converter.widget_to_input(widget_item)
+        assert isinstance(result, ChatMessage)
+        assert result.role == Role.USER
+        assert "widget_1" in result.text
+        assert "graphical UI widget" in result.text
+
+
+class TestSimpleToAgentInput:
+    """Tests for simple_to_agent_input helper function."""
+
+    async def test_simple_to_agent_input_empty_list(self):
+        """Test simple conversion with empty list."""
+        result = await simple_to_agent_input([])
+        assert result == []
+
+    async def test_simple_to_agent_input_with_text(self):
+        """Test simple conversion with text content."""
+        from datetime import datetime
+
+        from chatkit.types import UserMessageItem
+
+        input_item = UserMessageItem(
+            id="msg_1",
+            thread_id="thread_1",
+            created_at=datetime.now(),
+            type="user_message",
+            content=[UserMessageTextContent(text="Test message")],
+            attachments=[],
+            inference_options={},
+        )
+
+        result = await simple_to_agent_input(input_item)
+
+        assert len(result) == 1
+        assert isinstance(result[0], ChatMessage)
+        assert result[0].role == Role.USER
+        assert result[0].text == "Test message"

python/packages/chatkit/tests/test_streaming.py

@@ -0,0 +1,142 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Tests for Agent Framework to ChatKit streaming utilities."""
+
+from unittest.mock import Mock
+
+from agent_framework import AgentRunResponseUpdate, Role, TextContent
+from chatkit.types import (
+    ThreadItemAddedEvent,
+    ThreadItemDoneEvent,
+    ThreadItemUpdated,
+)
+
+from agent_framework_chatkit import stream_agent_response
+
+
+class TestStreamAgentResponse:
+    """Tests for stream_agent_response function."""
+
+    async def test_stream_empty_response(self):
+        """Test streaming empty response."""
+
+        async def empty_stream():
+            return
+            yield  # Make it a generator
+
+        events = []
+        async for event in stream_agent_response(empty_stream(), thread_id="test_thread"):
+            events.append(event)
+
+        assert len(events) == 0
+
+    async def test_stream_single_text_update(self):
+        """Test streaming single text update."""
+
+        async def single_update_stream():
+            yield AgentRunResponseUpdate(role=Role.ASSISTANT, contents=[TextContent(text="Hello world")])
+
+        events = []
+        async for event in stream_agent_response(single_update_stream(), thread_id="test_thread"):
+            events.append(event)
+
+        # Should have: item_added, item_updated (delta), item_done
+        assert len(events) == 3
+
+        # Check event types
+        assert isinstance(events[0], ThreadItemAddedEvent)
+        assert isinstance(events[1], ThreadItemUpdated)
+        assert isinstance(events[2], ThreadItemDoneEvent)
+
+        # Check delta event
+        assert events[1].update.delta == "Hello world"
+
+        # Check final message content
+        assert len(events[2].item.content) == 1
+        assert events[2].item.content[0].text == "Hello world"
+
+    async def test_stream_multiple_text_updates(self):
+        """Test streaming multiple text updates."""
+
+        async def multiple_updates_stream():
+            yield AgentRunResponseUpdate(role=Role.ASSISTANT, contents=[TextContent(text="Hello ")])
+            yield AgentRunResponseUpdate(role=Role.ASSISTANT, contents=[TextContent(text="world!")])
+
+        events = []
+        async for event in stream_agent_response(multiple_updates_stream(), thread_id="test_thread"):
+            events.append(event)
+
+        # Should have: item_added, item_updated (delta 1), item_updated (delta 2), item_done
+        assert len(events) == 4
+
+        # Check event types
+        assert isinstance(events[0], ThreadItemAddedEvent)
+        assert isinstance(events[1], ThreadItemUpdated)
+        assert isinstance(events[2], ThreadItemUpdated)
+        assert isinstance(events[3], ThreadItemDoneEvent)
+
+        # Check delta events
+        assert events[1].update.delta == "Hello "
+        assert events[2].update.delta == "world!"
+
+        # Check final accumulated text
+        final_message_event = events[-1]
+        assert isinstance(final_message_event, ThreadItemDoneEvent)
+        assert final_message_event.item.content[0].text == "Hello world!"
+
+    async def test_stream_with_custom_id_generator(self):
+        """Test streaming with custom ID generator."""
+
+        def custom_id_generator(item_type: str) -> str:
+            return f"custom_{item_type}_123"
+
+        async def single_update_stream():
+            yield AgentRunResponseUpdate(role=Role.ASSISTANT, contents=[TextContent(text="Test")])
+
+        events = []
+        async for event in stream_agent_response(
+            single_update_stream(), thread_id="test_thread", generate_id=custom_id_generator
+        ):
+            events.append(event)
+
+        # Check that custom IDs are used
+        message_added_event = events[0]
+        assert message_added_event.item.id == "custom_msg_123"
+
+    async def test_stream_empty_content_updates(self):
+        """Test streaming updates with empty content."""
+
+        async def empty_content_stream():
+            yield AgentRunResponseUpdate(role=Role.ASSISTANT, contents=[])
+            yield AgentRunResponseUpdate(role=Role.ASSISTANT, contents=None)
+
+        events = []
+        async for event in stream_agent_response(empty_content_stream(), thread_id="test_thread"):
+            events.append(event)
+
+        # Should have item_added and item_done
+        assert len(events) == 2
+        assert isinstance(events[0], ThreadItemAddedEvent)
+        assert isinstance(events[1], ThreadItemDoneEvent)
+
+        # Final message should have empty content
+        assert len(events[1].item.content) == 0
+
+    async def test_stream_non_text_content(self):
+        """Test streaming updates with non-text content."""
+        # Mock a content object without text attribute
+        non_text_content = Mock()
+        # Don't set text attribute
+        del non_text_content.text
+
+        async def non_text_stream():
+            yield AgentRunResponseUpdate(role=Role.ASSISTANT, contents=[non_text_content])
+
+        events = []
+        async for event in stream_agent_response(non_text_stream(), thread_id="test_thread"):
+            events.append(event)
+
+        # Should have item_added and item_done, but no content since no text
+        assert len(events) == 2
+        assert isinstance(events[0], ThreadItemAddedEvent)
+        assert isinstance(events[1], ThreadItemDoneEvent)

python/packages/copilotstudio/pyproject.toml

@@ -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.0b251028"
+version = "1.0.0b251104"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/core/agent_framework/_workflows/_handoff.py

@@ -80,6 +80,14 @@ def _clone_chat_agent(agent: ChatAgent) -> ChatAgent:
     options = agent.chat_options
     middleware = list(agent.middleware or [])
 
+    # Reconstruct the original tools list by combining regular tools with MCP tools.
+    # ChatAgent.__init__ separates MCP tools into _local_mcp_tools during initialization,
+    # so we need to recombine them here to pass the complete tools list to the constructor.
+    # This makes sure MCP tools are preserved when cloning agents for handoff workflows.
+    all_tools = list(options.tools) if options.tools else []
+    if agent._local_mcp_tools:
+        all_tools.extend(agent._local_mcp_tools)
+
     return ChatAgent(
         chat_client=agent.chat_client,
         instructions=options.instructions,
@@ -101,7 +109,7 @@ def _clone_chat_agent(agent: ChatAgent) -> ChatAgent:
         store=options.store,
         temperature=options.temperature,
         tool_choice=options.tool_choice,  # type: ignore[arg-type]
-        tools=list(options.tools) if options.tools else None,
+        tools=all_tools if all_tools else None,
         top_p=options.top_p,
         user=options.user,
         additional_chat_options=dict(options.additional_properties),

python/packages/core/agent_framework/chatkit/__init__.py

@@ -0,0 +1,23 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import importlib
+from typing import Any
+
+PACKAGE_NAME = "agent_framework_chatkit"
+PACKAGE_EXTRA = "chatkit"
+_IMPORTS = ["__version__", "ThreadItemConverter", "simple_to_agent_input", "stream_agent_response"]
+
+
+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

python/packages/core/agent_framework/chatkit/__init__.pyi

@@ -0,0 +1,10 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from agent_framework_chatkit import (
+    ThreadItemConverter,
+    __version__,
+    simple_to_agent_input,
+    stream_agent_response,
+)
+
+__all__ = ["ThreadItemConverter", "__version__", "simple_to_agent_input", "stream_agent_response"]

python/packages/core/pyproject.toml

@@ -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.0b251028"
+version = "1.0.0b251104"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/core/tests/workflow/test_handoff.py

@@ -3,6 +3,7 @@
 from collections.abc import AsyncIterable, AsyncIterator
 from dataclasses import dataclass
 from typing import Any, cast
+from unittest.mock import MagicMock
 
 import pytest
 
@@ -10,6 +11,7 @@ from agent_framework import (
     AgentRunResponse,
     AgentRunResponseUpdate,
     BaseAgent,
+    ChatAgent,
     ChatMessage,
     FunctionCallContent,
     HandoffBuilder,
@@ -20,6 +22,8 @@ from agent_framework import (
     WorkflowEvent,
     WorkflowOutputEvent,
 )
+from agent_framework._mcp import MCPTool
+from agent_framework._workflows._handoff import _clone_chat_agent
 
 
 @dataclass
@@ -368,3 +372,32 @@ async def test_handoff_async_termination_condition() -> None:
     user_messages = [msg for msg in final_conv_list if msg.role == Role.USER]
     assert len(user_messages) == 2
     assert termination_call_count > 0
+
+
+async def test_clone_chat_agent_preserves_mcp_tools() -> None:
+    """Test that _clone_chat_agent preserves MCP tools when cloning an agent."""
+    mock_chat_client = MagicMock()
+
+    mock_mcp_tool = MagicMock(spec=MCPTool)
+    mock_mcp_tool.name = "test_mcp_tool"
+
+    def sample_function() -> str:
+        return "test"
+
+    original_agent = ChatAgent(
+        chat_client=mock_chat_client,
+        name="TestAgent",
+        instructions="Test instructions",
+        tools=[mock_mcp_tool, sample_function],
+    )
+
+    assert hasattr(original_agent, "_local_mcp_tools")
+    assert len(original_agent._local_mcp_tools) == 1
+    assert original_agent._local_mcp_tools[0] == mock_mcp_tool
+
+    cloned_agent = _clone_chat_agent(original_agent)
+
+    assert hasattr(cloned_agent, "_local_mcp_tools")
+    assert len(cloned_agent._local_mcp_tools) == 1
+    assert cloned_agent._local_mcp_tools[0] == mock_mcp_tool
+    assert len(cloned_agent.chat_options.tools) == 1

python/packages/devui/pyproject.toml

@@ -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.0b251028"
+version = "1.0.0b251104"
 license-files = ["LICENSE"]
 urls.homepage = "https://github.com/microsoft/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/lab/pyproject.toml

@@ -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.0b251028"
+version = "1.0.0b251104"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/mem0/pyproject.toml

@@ -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.0b251028"
+version = "1.0.0b251104"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/purview/pyproject.toml

@@ -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.0b251028"
+version = "1.0.0b251104"
 license-files = ["LICENSE"]
 urls.homepage = "https://github.com/microsoft/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/packages/redis/pyproject.toml

@@ -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.0b251028"
+version = "1.0.0b251104"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"

python/pyproject.toml

@@ -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.0b251028"
+version = "1.0.0b251104"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -24,8 +24,10 @@ classifiers = [
 dependencies = [
     "agent-framework-core",
     "agent-framework-a2a",
+    "agent-framework-ag-ui",
     "agent-framework-anthropic",
     "agent-framework-azure-ai",
+    "agent-framework-chatkit",
     "agent-framework-copilotstudio",
     "agent-framework-devui",
     "agent-framework-lab",
@@ -88,7 +90,9 @@ members = [ "packages/*" ]
 agent-framework = { workspace = true }
 agent-framework-core = { workspace = true }
 agent-framework-a2a = { workspace = true }
+agent-framework-ag-ui = { workspace = true }
 agent-framework-azure-ai = { workspace = true }
+agent-framework-chatkit = { workspace = true }
 agent-framework-copilotstudio = { workspace = true }
 agent-framework-lab = { workspace = true }
 agent-framework-mem0 = { workspace = true }
@@ -239,7 +243,9 @@ cmd = """
 pytest --import-mode=importlib
 --cov=agent_framework
 --cov=agent_framework_a2a
+--cov=agent_framework_ag_ui
 --cov=agent_framework_azure_ai
+--cov=agent_framework_chatkit
 --cov=agent_framework_copilotstudio
 --cov=agent_framework_mem0
 --cov=agent_framework_redis

python/samples/demos/chatkit-integration/.gitignore

@@ -0,0 +1,4 @@
+*.db
+*.db-shm
+*.db-wal
+uploads/

python/samples/demos/chatkit-integration/README.md

@@ -0,0 +1,268 @@
+# ChatKit Integration Sample with Weather Agent and Image Analysis
+
+This sample demonstrates how to integrate Microsoft Agent Framework with OpenAI ChatKit. It provides a complete implementation of a weather assistant with interactive widget visualization, image analysis, and file upload support.
+
+**Features:**
+
+- Weather information with interactive widgets
+- Image analysis using vision models
+- Current time queries
+- File upload with attachment storage
+- Chat interface with streaming responses
+- City selector widget with one-click weather
+
+## Architecture
+
+```mermaid
+graph TB
+    subgraph Frontend["React Frontend (ChatKit UI)"]
+        UI[ChatKit Components]
+        Upload[File Upload]
+    end
+
+    subgraph Backend["FastAPI Server"]
+        FastAPI[FastAPI Endpoints]
+
+        subgraph ChatKit["WeatherChatKitServer"]
+            Respond[respond method]
+            Action[action method]
+        end
+
+        subgraph Stores["Data & Storage Layer"]
+            SQLite[SQLiteStore<br/>Store Protocol]
+            AttStore[FileBasedAttachmentStore<br/>AttachmentStore Protocol]
+            DB[(SQLite DB<br/>chatkit_demo.db)]
+            Files[/uploads directory/]
+        end
+
+        subgraph Integration["Agent Framework Integration"]
+            Converter[ThreadItemConverter]
+            Streamer[stream_agent_response]
+            Agent[ChatAgent]
+        end
+
+        Widgets[Widget Rendering<br/>render_weather_widget<br/>render_city_selector_widget]
+    end
+
+    subgraph Azure["Azure AI"]
+        Foundry[GPT-5<br/>with Vision]
+    end
+
+    UI -->|HTTP POST /chatkit| FastAPI
+    Upload -->|HTTP POST /upload/id| FastAPI
+
+    FastAPI --> ChatKit
+
+    ChatKit -->|save/load threads| SQLite
+    ChatKit -->|save/load attachments| AttStore
+    ChatKit -->|convert messages| Converter
+
+    SQLite -.->|persist| DB
+    AttStore -.->|save files| Files
+    AttStore -.->|save metadata| SQLite
+
+    Converter -->|ChatMessage array| Agent
+    Agent -->|AgentRunResponseUpdate| Streamer
+    Streamer -->|ThreadStreamEvent| ChatKit
+
+    ChatKit --> Widgets
+    Widgets -->|WidgetItem| ChatKit
+
+    Agent <-->|Chat Completions API| Foundry
+
+    ChatKit -->|ThreadStreamEvent| FastAPI
+    FastAPI -->|SSE Stream| UI
+
+    style ChatKit fill:#e1f5ff
+    style Stores fill:#fff4e1
+    style Integration fill:#f0e1ff
+    style Azure fill:#e1ffe1
+```
+
+### Server Implementation
+
+The sample implements a ChatKit server using the `ChatKitServer` base class from the `chatkit` package:
+
+**Core Components:**
+
+- **`WeatherChatKitServer`**: Custom ChatKit server implementation that:
+
+  - Extends `ChatKitServer[dict[str, Any]]`
+  - Uses Agent Framework's `ChatAgent` with Azure OpenAI
+  - Converts ChatKit messages to Agent Framework format using `ThreadItemConverter`
+  - Streams responses back to ChatKit using `stream_agent_response`
+  - Creates and streams interactive widgets after agent responses
+
+- **`SQLiteStore`**: Data persistence layer that:
+
+  - Implements the `Store[dict[str, Any]]` protocol from ChatKit
+  - Persists threads, messages, and attachment metadata in SQLite
+  - Provides thread management and item history
+  - Stores attachment metadata for the upload lifecycle
+
+- **`FileBasedAttachmentStore`**: File storage implementation that:
+  - Implements the `AttachmentStore[dict[str, Any]]` protocol from ChatKit
+  - Stores uploaded files on the local filesystem (in `./uploads` directory)
+  - Generates upload URLs for two-phase file upload
+  - Saves attachment metadata to the data store for upload tracking
+  - Provides preview URLs for images
+
+**Key Integration Points:**
+
+```python
+# Converting ChatKit messages to Agent Framework
+converter = ThreadItemConverter(
+    attachment_data_fetcher=self._fetch_attachment_data
+)
+agent_messages = await converter.to_agent_input(user_message_item)
+
+# Running agent and streaming back to ChatKit
+async for event in stream_agent_response(
+    self.weather_agent.run_stream(agent_messages),
+    thread_id=thread.id,
+):
+    yield event
+
+# Streaming widgets
+widget = render_weather_widget(weather_data)
+async for event in stream_widget(thread_id=thread.id, widget=widget):
+    yield event
+```
+
+## Installation and Setup
+
+### Prerequisites
+
+- Python 3.10+
+- Node.js 18.18+ and npm 9+
+- Azure OpenAI service configured
+- Azure CLI for authentication (`az login`)
+
+### Backend Setup
+
+1. **Install Python packages:**
+
+```bash
+cd python/samples/demos/chatkit-integration
+pip install agent-framework-chatkit fastapi uvicorn azure-identity
+```
+
+2. **Configure Azure OpenAI:**
+
+```bash
+export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
+export AZURE_OPENAI_API_VERSION="2024-06-01"
+export AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4o"
+```
+
+3. **Authenticate with Azure:**
+
+```bash
+az login
+```
+
+### Frontend Setup
+
+Install the Node.js dependencies:
+
+```bash
+cd frontend
+npm install
+```
+
+## How to Run
+
+### Start the Backend Server
+
+From the `chatkit-integration` directory:
+
+```bash
+python app.py
+```
+
+Or with auto-reload for development:
+
+```bash
+uvicorn app:app --host 127.0.0.1 --port 8001 --reload
+```
+
+The backend will start on `http://localhost:8001`
+
+### Start the Frontend Development Server
+
+In a new terminal, from the `frontend` directory:
+
+```bash
+npm run dev
+```
+
+The frontend will start on `http://localhost:5171`
+
+### Access the Application
+
+Open your browser and navigate to:
+
+```
+http://localhost:5171
+```
+
+You can now:
+
+- Ask about weather in any location (weather widgets display automatically)
+- Upload images for analysis using the attachment button
+- Get the current time
+- Ask to see available cities and click city buttons for instant weather
+
+### Project Structure
+
+```
+chatkit-integration/
+├── app.py                    # FastAPI backend with ChatKitServer implementation
+├── store.py                  # SQLiteStore implementation
+├── attachment_store.py       # FileBasedAttachmentStore implementation
+├── weather_widget.py         # Widget rendering functions
+├── chatkit_demo.db          # SQLite database (auto-created)
+├── uploads/                  # Uploaded files directory (auto-created)
+└── frontend/
+    ├── package.json
+    ├── vite.config.ts
+    ├── index.html
+    └── src/
+        ├── main.tsx
+        └── App.tsx           # ChatKit UI integration
+```
+
+### Configuration
+
+You can customize the application by editing constants at the top of `app.py`:
+
+```python
+# Server configuration
+SERVER_HOST = "127.0.0.1"  # Bind to localhost only for security (local dev)
+SERVER_PORT = 8001
+SERVER_BASE_URL = f"http://localhost:{SERVER_PORT}"
+
+# Database configuration
+DATABASE_PATH = "chatkit_demo.db"
+
+# File storage configuration
+UPLOADS_DIRECTORY = "./uploads"
+
+# User context
+DEFAULT_USER_ID = "demo_user"
+```
+
+### Sample Conversations
+
+Try these example queries:
+
+- "What's the weather like in Tokyo?"
+- "Show me available cities" (displays interactive city selector)
+- "What's the current time?"
+- Upload an image and ask "What do you see in this image?"
+
+## Learn More
+
+- [Agent Framework Documentation](https://aka.ms/agent-framework)
+- [ChatKit Documentation](https://platform.openai.com/docs/guides/chatkit)
+- [Azure OpenAI Documentation](https://learn.microsoft.com/en-us/azure/ai-foundry/)

python/samples/demos/chatkit-integration/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) Microsoft. All rights reserved.

python/samples/demos/chatkit-integration/app.py

@@ -0,0 +1,538 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""
+ChatKit Integration Sample with Weather Agent and Image Analysis
+
+This sample demonstrates how to integrate Microsoft Agent Framework with OpenAI ChatKit
+using a weather tool with widget visualization, image analysis, and Azure OpenAI. It shows
+a complete ChatKit server implementation using Agent Framework agents with proper FastAPI
+setup, interactive weather widgets, and vision capabilities for analyzing uploaded images.
+"""
+
+import logging
+from collections.abc import AsyncIterator, Callable
+from datetime import datetime, timezone
+from random import randint
+from typing import Annotated, Any
+
+import uvicorn
+from azure.identity import AzureCliCredential
+from fastapi import FastAPI, File, Request, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse, Response, StreamingResponse
+from pydantic import Field
+
+# ============================================================================
+# Configuration Constants
+# ============================================================================
+
+# Server configuration
+SERVER_HOST = "127.0.0.1"  # Bind to localhost only for security (local dev)
+SERVER_PORT = 8001
+SERVER_BASE_URL = f"http://localhost:{SERVER_PORT}"
+
+# Database configuration
+DATABASE_PATH = "chatkit_demo.db"
+
+# File storage configuration
+UPLOADS_DIRECTORY = "./uploads"
+
+# User context
+DEFAULT_USER_ID = "demo_user"
+
+# Logging configuration
+LOG_LEVEL = logging.INFO
+LOG_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+LOG_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+# ============================================================================
+# Logging Setup
+# ============================================================================
+
+logging.basicConfig(
+    level=LOG_LEVEL,
+    format=LOG_FORMAT,
+    datefmt=LOG_DATE_FORMAT,
+)
+logger = logging.getLogger(__name__)
+
+# Agent Framework imports
+from agent_framework import AgentRunResponseUpdate, ChatAgent, ChatMessage, FunctionResultContent, Role
+from agent_framework.azure import AzureOpenAIChatClient
+
+# Agent Framework ChatKit integration
+from agent_framework_chatkit import ThreadItemConverter, stream_agent_response
+
+# Local imports
+from attachment_store import FileBasedAttachmentStore
+
+# ChatKit imports
+from chatkit.actions import Action
+from chatkit.server import ChatKitServer
+from chatkit.store import StoreItemType, default_generate_id
+from chatkit.types import (
+    ThreadItemDoneEvent,
+    ThreadMetadata,
+    ThreadStreamEvent,
+    UserMessageItem,
+    WidgetItem,
+)
+from chatkit.widgets import WidgetRoot
+from store import SQLiteStore
+from weather_widget import (
+    WeatherData,
+    city_selector_copy_text,
+    render_city_selector_widget,
+    render_weather_widget,
+    weather_widget_copy_text,
+)
+
+
+class WeatherResponse(str):
+    """A string response that also carries WeatherData for widget creation."""
+
+    def __new__(cls, text: str, weather_data: WeatherData):
+        instance = super().__new__(cls, text)
+        instance.weather_data = weather_data  # type: ignore
+        return instance
+
+
+async def stream_widget(
+    thread_id: str,
+    widget: WidgetRoot,
+    copy_text: str | None = None,
+    generate_id: Callable[[StoreItemType], str] = default_generate_id,
+) -> AsyncIterator[ThreadStreamEvent]:
+    """Stream a ChatKit widget as a ThreadStreamEvent.
+
+    This helper function creates a ChatKit widget item and yields it as a
+    ThreadItemDoneEvent that can be consumed by the ChatKit UI.
+
+    Args:
+        thread_id: The ChatKit thread ID for the conversation.
+        widget: The ChatKit widget to display.
+        copy_text: Optional text representation of the widget for copy/paste.
+        generate_id: Optional function to generate IDs for ChatKit items.
+
+    Yields:
+        ThreadStreamEvent: ChatKit event containing the widget.
+    """
+    item_id = generate_id("message")
+
+    widget_item = WidgetItem(
+        id=item_id,
+        thread_id=thread_id,
+        created_at=datetime.now(),
+        widget=widget,
+        copy_text=copy_text,
+    )
+
+    yield ThreadItemDoneEvent(type="thread.item.done", item=widget_item)
+
+
+def get_weather(
+    location: Annotated[str, Field(description="The location to get the weather for.")],
+) -> str:
+    """Get the weather for a given location.
+
+    Returns a string description with embedded WeatherData for widget creation.
+    """
+    logger.info(f"Fetching weather for location: {location}")
+
+    conditions = ["sunny", "cloudy", "rainy", "stormy", "snowy", "foggy"]
+    temperature = randint(-5, 35)
+    condition = conditions[randint(0, len(conditions) - 1)]
+
+    # Add some realistic details
+    humidity = randint(30, 90)
+    wind_speed = randint(5, 25)
+
+    weather_data = WeatherData(
+        location=location,
+        condition=condition,
+        temperature=temperature,
+        humidity=humidity,
+        wind_speed=wind_speed,
+    )
+
+    logger.debug(f"Weather data generated: {condition}, {temperature}°C, {humidity}% humidity, {wind_speed} km/h wind")
+
+    # Return a WeatherResponse that is both a string (for the LLM) and carries structured data
+    text = (
+        f"Weather in {location}:\n"
+        f"• Condition: {condition.title()}\n"
+        f"• Temperature: {temperature}°C\n"
+        f"• Humidity: {humidity}%\n"
+        f"• Wind: {wind_speed} km/h"
+    )
+    return WeatherResponse(text, weather_data)
+
+
+def get_time() -> str:
+    """Get the current UTC time."""
+    current_time = datetime.now(timezone.utc)
+    logger.info("Getting current UTC time")
+    return f"Current UTC time: {current_time.strftime('%Y-%m-%d %H:%M:%S')} UTC"
+
+
+def show_city_selector() -> str:
+    """Show an interactive city selector widget to the user.
+
+    This function triggers the display of a widget that allows users
+    to select from popular cities to get weather information.
+
+    Returns a special marker string that will be detected to show the widget.
+    """
+    logger.info("Activating city selector widget")
+    return "__SHOW_CITY_SELECTOR__"
+
+
+class WeatherChatKitServer(ChatKitServer[dict[str, Any]]):
+    """ChatKit server implementation using Agent Framework.
+
+    This server integrates Agent Framework agents with ChatKit's server protocol,
+    providing weather information with interactive widgets and time queries through Azure OpenAI.
+    """
+
+    def __init__(self, data_store: SQLiteStore, attachment_store: FileBasedAttachmentStore):
+        super().__init__(data_store, attachment_store)
+
+        logger.info("Initializing WeatherChatKitServer")
+
+        # Create Agent Framework agent with Azure OpenAI
+        # For authentication, run `az login` command in terminal
+        try:
+            self.weather_agent = ChatAgent(
+                chat_client=AzureOpenAIChatClient(credential=AzureCliCredential()),
+                instructions=(
+                    "You are a helpful weather assistant with image analysis capabilities. "
+                    "You can provide weather information for any location, tell the current time, "
+                    "and analyze images that users upload. Be friendly and informative in your responses.\n\n"
+                    "If a user asks to see a list of cities or wants to choose from available cities, "
+                    "use the show_city_selector tool to display an interactive city selector.\n\n"
+                    "When users upload images, you will automatically receive them and can analyze their content. "
+                    "Describe what you see in detail and be helpful in answering questions about the images."
+                ),
+                tools=[get_weather, get_time, show_city_selector],
+            )
+            logger.info("Weather agent initialized successfully with Azure OpenAI")
+        except Exception as e:
+            logger.error(f"Failed to initialize weather agent: {e}")
+            raise
+
+        # Create ThreadItemConverter with attachment data fetcher
+        self.converter = ThreadItemConverter(
+            attachment_data_fetcher=self._fetch_attachment_data,
+        )
+
+        logger.info("WeatherChatKitServer initialized")
+
+    async def _fetch_attachment_data(self, attachment_id: str) -> bytes:
+        """Fetch attachment binary data for the converter.
+
+        Args:
+            attachment_id: The ID of the attachment to fetch.
+
+        Returns:
+            The binary data of the attachment.
+        """
+        return await attachment_store.read_attachment_bytes(attachment_id)
+
+    async def respond(
+        self,
+        thread: ThreadMetadata,
+        input_user_message: UserMessageItem | None,
+        context: dict[str, Any],
+    ) -> AsyncIterator[ThreadStreamEvent]:
+        """Handle incoming user messages and generate responses.
+
+        This method converts ChatKit messages to Agent Framework format using ThreadItemConverter,
+        runs the agent, converts the response back to ChatKit events using stream_agent_response,
+        and creates interactive weather widgets when weather data is queried.
+        """
+        from agent_framework import FunctionResultContent
+
+        if input_user_message is None:
+            logger.debug("Received None user message, skipping")
+            return
+
+        logger.info(f"Processing message for thread: {thread.id}")
+
+        try:
+            # Track weather data and city selector flag for this request
+            weather_data: WeatherData | None = None
+            show_city_selector = False
+
+            # Convert ChatKit user message to Agent Framework ChatMessage using ThreadItemConverter
+            agent_messages = await self.converter.to_agent_input(input_user_message)
+
+            if not agent_messages:
+                logger.warning("No messages after conversion")
+                return
+
+            logger.info(f"Running agent with {len(agent_messages)} message(s)")
+
+            # Run the Agent Framework agent with streaming
+            agent_stream = self.weather_agent.run_stream(agent_messages)
+
+            # Create an intercepting stream that extracts function results while passing through updates
+            async def intercept_stream() -> AsyncIterator[AgentRunResponseUpdate]:
+                nonlocal weather_data, show_city_selector
+                async for update in agent_stream:
+                    # Check for function results in the update
+                    if update.contents:
+                        for content in update.contents:
+                            if isinstance(content, FunctionResultContent):
+                                result = content.result
+
+                                # Check if it's a WeatherResponse (string subclass with weather_data attribute)
+                                if isinstance(result, str) and hasattr(result, "weather_data"):
+                                    extracted_data = getattr(result, "weather_data", None)
+                                    if isinstance(extracted_data, WeatherData):
+                                        weather_data = extracted_data
+                                        logger.info(f"Weather data extracted: {weather_data.location}")
+                                # Check if it's the city selector marker
+                                elif isinstance(result, str) and result == "__SHOW_CITY_SELECTOR__":
+                                    show_city_selector = True
+                                    logger.info("City selector flag detected")
+                    yield update
+
+            # Stream updates as ChatKit events with interception
+            async for event in stream_agent_response(
+                intercept_stream(),
+                thread_id=thread.id,
+            ):
+                yield event
+
+            # If weather data was collected during the tool call, create a widget
+            if weather_data is not None and isinstance(weather_data, WeatherData):
+                logger.info(f"Creating weather widget for location: {weather_data.location}")
+                # Create weather widget
+                widget = render_weather_widget(weather_data)
+                copy_text = weather_widget_copy_text(weather_data)
+
+                # Stream the widget
+                async for widget_event in stream_widget(thread_id=thread.id, widget=widget, copy_text=copy_text):
+                    yield widget_event
+                logger.debug("Weather widget streamed successfully")
+
+            # If city selector should be shown, create and stream that widget
+            if show_city_selector:
+                logger.info("Creating city selector widget")
+                # Create city selector widget
+                selector_widget = render_city_selector_widget()
+                selector_copy_text = city_selector_copy_text()
+
+                # Stream the widget
+                async for widget_event in stream_widget(
+                    thread_id=thread.id, widget=selector_widget, copy_text=selector_copy_text
+                ):
+                    yield widget_event
+                logger.debug("City selector widget streamed successfully")
+
+            logger.info(f"Completed processing message for thread: {thread.id}")
+
+        except Exception as e:
+            logger.error(f"Error processing message for thread {thread.id}: {e}", exc_info=True)
+
+    async def action(
+        self,
+        thread: ThreadMetadata,
+        action: Action[str, Any],
+        sender: WidgetItem | None,
+        context: dict[str, Any],
+    ) -> AsyncIterator[ThreadStreamEvent]:
+        """Handle widget actions from the frontend.
+
+        This method processes actions triggered by interactive widgets,
+        such as city selection from the city selector widget.
+        """
+
+        logger.info(f"Received action: {action.type} for thread: {thread.id}")
+
+        if action.type == "city_selected":
+            # Extract city information from the action payload
+            city_label = action.payload.get("city_label", "Unknown")
+
+            logger.info(f"City selected: {city_label}")
+            logger.debug(f"Action payload: {action.payload}")
+
+            # Track weather data for this request
+            weather_data: WeatherData | None = None
+
+            # Create an agent message asking about the weather
+            agent_messages = [ChatMessage(role=Role.USER, text=f"What's the weather in {city_label}?")]
+
+            logger.debug(f"Processing weather query: {agent_messages[0].text}")
+
+            # Run the Agent Framework agent with streaming
+            agent_stream = self.weather_agent.run_stream(agent_messages)
+
+            # Create an intercepting stream that extracts function results while passing through updates
+            async def intercept_stream() -> AsyncIterator[AgentRunResponseUpdate]:
+                nonlocal weather_data
+                async for update in agent_stream:
+                    # Check for function results in the update
+                    if update.contents:
+                        for content in update.contents:
+                            if isinstance(content, FunctionResultContent):
+                                result = content.result
+
+                                # Check if it's a WeatherResponse (string subclass with weather_data attribute)
+                                if isinstance(result, str) and hasattr(result, "weather_data"):
+                                    extracted_data = getattr(result, "weather_data", None)
+                                    if isinstance(extracted_data, WeatherData):
+                                        weather_data = extracted_data
+                                        logger.info(f"Weather data extracted: {weather_data.location}")
+                    yield update
+
+            # Stream updates as ChatKit events with interception
+            async for event in stream_agent_response(
+                intercept_stream(),
+                thread_id=thread.id,
+            ):
+                yield event
+
+            # If weather data was collected during the tool call, create a widget
+            if weather_data is not None and isinstance(weather_data, WeatherData):
+                logger.info(f"Creating weather widget for: {weather_data.location}")
+                # Create weather widget
+                widget = render_weather_widget(weather_data)
+                copy_text = weather_widget_copy_text(weather_data)
+
+                # Stream the widget
+                async for widget_event in stream_widget(thread_id=thread.id, widget=widget, copy_text=copy_text):
+                    yield widget_event
+                logger.debug("Weather widget created successfully from action")
+            else:
+                logger.warning("No weather data available to create widget after action")
+
+
+# FastAPI application setup
+app = FastAPI(
+    title="ChatKit Weather & Vision Agent",
+    description="Weather and image analysis assistant powered by Agent Framework and Azure OpenAI",
+    version="1.0.0",
+)
+
+# Add CORS middleware to allow frontend connections
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production, specify exact origins
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Initialize data store and ChatKit server
+logger.info("Initializing application components")
+data_store = SQLiteStore(db_path=DATABASE_PATH)
+attachment_store = FileBasedAttachmentStore(
+    uploads_dir=UPLOADS_DIRECTORY,
+    base_url=SERVER_BASE_URL,
+    data_store=data_store,
+)
+chatkit_server = WeatherChatKitServer(data_store, attachment_store)
+logger.info("Application initialization complete")
+
+
+@app.post("/chatkit")
+async def chatkit_endpoint(request: Request):
+    """Main ChatKit endpoint that handles all ChatKit requests.
+
+    This endpoint follows the ChatKit server protocol and handles both
+    streaming and non-streaming responses.
+    """
+    logger.debug(f"Received ChatKit request from {request.client}")
+    request_body = await request.body()
+
+    # Create context following the working examples pattern
+    context = {"request": request}
+
+    try:
+        # Process the request using ChatKit server
+        result = await chatkit_server.process(request_body, context)
+
+        # Return appropriate response type
+        if hasattr(result, "__aiter__"):  # StreamingResult
+            logger.debug("Returning streaming response")
+            return StreamingResponse(result, media_type="text/event-stream")  # type: ignore[arg-type]
+        # NonStreamingResult
+        logger.debug("Returning non-streaming response")
+        return Response(content=result.json, media_type="application/json")  # type: ignore[union-attr]
+    except Exception as e:
+        logger.error(f"Error processing ChatKit request: {e}", exc_info=True)
+        raise
+
+
+@app.post("/upload/{attachment_id}")
+async def upload_file(attachment_id: str, file: UploadFile = File(...)):
+    """Handle file upload for two-phase upload.
+
+    The client POSTs the file bytes here after creating the attachment
+    via the ChatKit attachments.create endpoint.
+    """
+    logger.info(f"Receiving file upload for attachment: {attachment_id}")
+
+    try:
+        # Read file contents
+        contents = await file.read()
+
+        # Save to disk
+        file_path = attachment_store.get_file_path(attachment_id)
+        file_path.write_bytes(contents)
+
+        logger.info(f"Saved {len(contents)} bytes to {file_path}")
+
+        # Load the attachment metadata from the data store
+        attachment = await data_store.load_attachment(attachment_id, {"user_id": DEFAULT_USER_ID})
+
+        # Clear the upload_url since upload is complete
+        attachment.upload_url = None
+
+        # Save the updated attachment back to the store
+        await data_store.save_attachment(attachment, {"user_id": DEFAULT_USER_ID})
+
+        # Return the attachment metadata as JSON
+        return JSONResponse(content=attachment.model_dump(mode="json"))
+
+    except Exception as e:
+        logger.error(f"Error uploading file for attachment {attachment_id}: {e}", exc_info=True)
+        return JSONResponse(status_code=500, content={"error": f"Failed to upload file: {str(e)}"})
+
+
+@app.get("/preview/{attachment_id}")
+async def preview_image(attachment_id: str):
+    """Serve image preview/thumbnail.
+
+    For simplicity, this serves the full image. In production, you should
+    generate and cache thumbnails.
+    """
+    logger.debug(f"Serving preview for attachment: {attachment_id}")
+
+    try:
+        file_path = attachment_store.get_file_path(attachment_id)
+
+        if not file_path.exists():
+            return JSONResponse(status_code=404, content={"error": "File not found"})
+
+        # Determine media type from file extension or attachment metadata
+        # For simplicity, we'll try to load from the store
+        try:
+            attachment = await data_store.load_attachment(attachment_id, {"user_id": DEFAULT_USER_ID})
+            media_type = attachment.mime_type
+        except Exception:
+            # Default to binary if we can't determine
+            media_type = "application/octet-stream"
+
+        return FileResponse(file_path, media_type=media_type)
+
+    except Exception as e:
+        logger.error(f"Error serving preview for attachment {attachment_id}: {e}", exc_info=True)
+        return JSONResponse(status_code=500, content={"error": str(e)})
+
+
+if __name__ == "__main__":
+    # Run the server
+    logger.info(f"Starting ChatKit Weather Agent server on {SERVER_HOST}:{SERVER_PORT}")
+    uvicorn.run(app, host=SERVER_HOST, port=SERVER_PORT, log_level="info")

python/samples/demos/chatkit-integration/attachment_store.py

@@ -0,0 +1,121 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""File-based AttachmentStore implementation for ChatKit.
+
+This module provides a simple AttachmentStore implementation that stores
+uploaded files on the local filesystem. In production, you should use
+cloud storage like S3, Azure Blob Storage, or Google Cloud Storage.
+"""
+
+from pathlib import Path
+from typing import Any, TYPE_CHECKING
+
+from chatkit.store import AttachmentStore
+from chatkit.types import Attachment, AttachmentCreateParams, FileAttachment, ImageAttachment
+from pydantic import AnyUrl
+
+if TYPE_CHECKING:
+    from store import SQLiteStore
+
+
+class FileBasedAttachmentStore(AttachmentStore[dict[str, Any]]):
+    """File-based AttachmentStore that stores files on local disk.
+
+    This implementation stores uploaded files in a local directory and provides
+    upload URLs that point to the FastAPI upload endpoint. It supports both
+    image and file attachments.
+
+    Features:
+    - Stores files in a local uploads directory
+    - Generates upload URLs for two-phase upload
+    - Generates preview URLs for images
+    - Proper cleanup on deletion
+
+    Note: This is for demonstration purposes. In production, use cloud storage
+    with signed URLs for better security and scalability.
+    """
+
+    def __init__(
+        self,
+        uploads_dir: str = "./uploads",
+        base_url: str = "http://localhost:8001",
+        data_store: "SQLiteStore | None" = None,
+    ):
+        """Initialize the file-based attachment store.
+
+        Args:
+            uploads_dir: Directory where uploaded files will be stored
+            base_url: Base URL for generating upload and preview URLs
+            data_store: Optional data store to persist attachment metadata
+        """
+        self.uploads_dir = Path(uploads_dir)
+        self.base_url = base_url.rstrip("/")
+        self.data_store = data_store
+        
+        # Create uploads directory if it doesn't exist
+        self.uploads_dir.mkdir(parents=True, exist_ok=True)
+
+    def get_file_path(self, attachment_id: str) -> Path:
+        """Get the filesystem path for an attachment."""
+        return self.uploads_dir / attachment_id
+
+    async def delete_attachment(self, attachment_id: str, context: dict[str, Any]) -> None:
+        """Delete an attachment and its file from disk."""
+        file_path = self.get_file_path(attachment_id)
+        if file_path.exists():
+            file_path.unlink()
+
+    async def create_attachment(
+        self, input: AttachmentCreateParams, context: dict[str, Any]
+    ) -> Attachment:
+        """Create an attachment with upload URL for two-phase upload.
+
+        This creates the attachment metadata and returns upload URLs that
+        the client will use to POST the actual file bytes.
+        """
+        # Generate unique ID for this attachment
+        attachment_id = self.generate_attachment_id(input.mime_type, context)
+        
+        # Generate upload URL that points to our FastAPI upload endpoint
+        upload_url = f"{self.base_url}/upload/{attachment_id}"
+
+        # Create appropriate attachment type based on MIME type
+        if input.mime_type.startswith("image/"):
+            # For images, also provide a preview URL
+            preview_url = f"{self.base_url}/preview/{attachment_id}"
+            
+            attachment = ImageAttachment(
+                id=attachment_id,
+                type="image",
+                mime_type=input.mime_type,
+                name=input.name,
+                upload_url=AnyUrl(upload_url),
+                preview_url=AnyUrl(preview_url),
+            )
+        else:
+            # For files, just provide upload URL
+            attachment = FileAttachment(
+                id=attachment_id,
+                type="file",
+                mime_type=input.mime_type,
+                name=input.name,
+                upload_url=AnyUrl(upload_url),
+            )
+
+        # Save attachment metadata to data store so it's available during upload
+        if self.data_store is not None:
+            await self.data_store.save_attachment(attachment, context)
+
+        return attachment
+
+    async def read_attachment_bytes(self, attachment_id: str) -> bytes:
+        """Read the raw bytes of an uploaded attachment.
+
+        This is used by the ThreadItemConverter to create base64-encoded
+        content for sending to the Agent Framework.
+        """
+        file_path = self.get_file_path(attachment_id)
+        if not file_path.exists():
+            raise FileNotFoundError(f"Attachment {attachment_id} not found on disk")
+        
+        return file_path.read_bytes()

python/samples/demos/chatkit-integration/frontend/index.html

@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ChatKit + Agent Framework Demo</title>
+    <script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+        height: 100vh;
+        display: flex;
+        flex-direction: column;
+      }
+
+      header {
+        padding: 1rem;
+        background: #f5f5f5;
+        border-bottom: 1px solid #ddd;
+      }
+
+      h1 {
+        font-size: 1.5rem;
+        margin-bottom: 0.5rem;
+      }
+
+      p {
+        color: #666;
+        font-size: 0.9rem;
+      }
+
+      #root {
+        flex: 1;
+        overflow: hidden;
+      }
+    </style>
+  </head>
+  <body>
+    <header>
+      <h1>ChatKit + Agent Framework Demo</h1>
+      <p>Simple weather assistant powered by Agent Framework and ChatKit</p>
+    </header>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

python/samples/demos/chatkit-integration/frontend/package.json

@@ -0,0 +1,27 @@
+{
+    "name": "chatkit-agent-framework-demo",
+    "version": "0.1.0",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "dev": "vite",
+        "build": "vite build",
+        "preview": "vite preview"
+    },
+    "engines": {
+        "node": ">=18.18",
+        "npm": ">=9"
+    },
+    "dependencies": {
+        "@openai/chatkit-react": "^0",
+        "react": "^19.2.0",
+        "react-dom": "^19.2.0"
+    },
+    "devDependencies": {
+        "@types/react": "^19.2.0",
+        "@types/react-dom": "^19.2.0",
+        "@vitejs/plugin-react-swc": "^3.5.0",
+        "typescript": "^5.4.0",
+        "vite": "^7.1.9"
+    }
+}

python/samples/demos/chatkit-integration/frontend/src/App.tsx

@@ -0,0 +1,33 @@
+import { ChatKit, useChatKit } from "@openai/chatkit-react";
+
+const CHATKIT_API_URL = "/chatkit";
+const CHATKIT_API_DOMAIN_KEY =
+  import.meta.env.VITE_CHATKIT_API_DOMAIN_KEY ?? "domain_pk_localhost_dev";
+
+export default function App() {
+  const chatkit = useChatKit({
+    api: {
+      url: CHATKIT_API_URL,
+      domainKey: CHATKIT_API_DOMAIN_KEY,
+      uploadStrategy: { type: "two_phase" },
+    },
+    startScreen: {
+      greeting: "Hello! I'm your weather and image analysis assistant. Ask me about the weather in any location or upload images for me to analyze.",
+      prompts: [
+        { label: "Weather in New York", prompt: "What's the weather in New York?" },
+        { label: "Select City to Get Weather", prompt: "Show me the city selector for weather" },
+        { label: "Current Time", prompt: "What time is it?" },
+        { label: "Analyze an Image", prompt: "I'll upload an image for you to analyze" },
+      ],
+    },
+    composer: {
+      placeholder: "Ask about weather or upload an image...",
+      attachments: {
+        enabled: true,
+        accept: { "image/*": [".png", ".jpg", ".jpeg", ".gif", ".webp"] },
+      },
+    },
+  });
+
+  return <ChatKit control={chatkit.control} style={{ height: "100%" }} />;
+}

python/samples/demos/chatkit-integration/frontend/src/main.tsx

@@ -0,0 +1,15 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+
+const container = document.getElementById("root");
+
+if (!container) {
+  throw new Error("Root element with id 'root' not found");
+}
+
+createRoot(container).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

python/samples/demos/chatkit-integration/frontend/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />