Removed unnecessary export command

* Add declarative HttpRequestAction support to workflows

* Clean up response body for diagnostics  and fix tests.

* Fix merge with main.

* Remove redundant fallback for request content headers.

* Add declarative InvokeHttpRequest sample

* Fix solution file and update sample yaml comments

* Add final newline to sample class to fix formatting failure

.gitignore

@@ -242,3 +242,7 @@ python/dotnet-ref
 # Generated filtered solution files (created by eng/scripts/New-FilteredSolution.ps1)
 dotnet/filtered-*.slnx
 **/*.lscache
+
+# Local tool state
+.omc/
+.omx/

dotnet/agent-framework-dotnet.slnx

@@ -163,10 +163,10 @@
     <Project Path="samples/02-agents/AgentsWithFoundry/Agent_Step25_ToolboxServerSideTools/Agent_Step25_ToolboxServerSideTools.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/Evaluation/">
-    <Project Path="samples/02-agents/Evaluation/Evaluation_SimpleEval/Evaluation_SimpleEval.csproj" />
     <Project Path="samples/02-agents/Evaluation/Evaluation_CustomEvals/Evaluation_CustomEvals.csproj" />
     <Project Path="samples/02-agents/Evaluation/Evaluation_ExpectedOutputs/Evaluation_ExpectedOutputs.csproj" />
     <Project Path="samples/02-agents/Evaluation/Evaluation_Multimodal/Evaluation_Multimodal.csproj" />
+    <Project Path="samples/02-agents/Evaluation/Evaluation_SimpleEval/Evaluation_SimpleEval.csproj" />
   </Folder>
   <Folder Name="/Samples/02-agents/AgentWithMemory/">
     <File Path="samples/02-agents/AgentWithMemory/README.md" />
@@ -226,6 +226,7 @@
     <Project Path="samples/03-workflows/Declarative/HostedWorkflow/HostedWorkflow.csproj" />
     <Project Path="samples/03-workflows/Declarative/InputArguments/InputArguments.csproj" />
     <Project Path="samples/03-workflows/Declarative/InvokeFunctionTool/InvokeFunctionTool.csproj" />
+    <Project Path="samples/03-workflows/Declarative/InvokeHttpRequest/InvokeHttpRequest.csproj" />
     <Project Path="samples/03-workflows/Declarative/InvokeMcpTool/InvokeMcpTool.csproj" />
     <Project Path="samples/03-workflows/Declarative/Marketing/Marketing.csproj" />
     <Project Path="samples/03-workflows/Declarative/StudentTeacher/StudentTeacher.csproj" />
@@ -347,17 +348,17 @@
     <File Path="samples/02-agents/A2A/README.md" />
     <Project Path="samples/02-agents/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj" />
     <Project Path="samples/02-agents/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj" />
-    <Project Path="samples/02-agents/A2A/A2AAgent_StreamReconnection/A2AAgent_StreamReconnection.csproj" />
     <Project Path="samples/02-agents/A2A/A2AAgent_ProtocolSelection/A2AAgent_ProtocolSelection.csproj" />
+    <Project Path="samples/02-agents/A2A/A2AAgent_StreamReconnection/A2AAgent_StreamReconnection.csproj" />
   </Folder>  
   <Folder Name="/Samples/05-end-to-end/">
     <Project Path="samples/05-end-to-end/AgentWithPurview/AgentWithPurview.csproj" />
     <Project Path="samples/05-end-to-end/M365Agent/M365Agent.csproj" />
   </Folder>
   <Folder Name="/Samples/05-end-to-end/Evaluation/">
+    <Project Path="samples/05-end-to-end/Evaluation/Evaluation_ConversationSplits/Evaluation_ConversationSplits.csproj" />
     <Project Path="samples/05-end-to-end/Evaluation/Evaluation_FoundryQuality/Evaluation_FoundryQuality.csproj" />
     <Project Path="samples/05-end-to-end/Evaluation/Evaluation_MixedProviders/Evaluation_MixedProviders.csproj" />
-    <Project Path="samples/05-end-to-end/Evaluation/Evaluation_ConversationSplits/Evaluation_ConversationSplits.csproj" />
   </Folder>
   <Folder Name="/Samples/05-end-to-end/A2AClientServer/">
     <File Path="samples/05-end-to-end/A2AClientServer/README.md" />
@@ -543,8 +544,8 @@
     <Project Path="src/Microsoft.Agents.AI.Declarative/Microsoft.Agents.AI.Declarative.csproj" />
     <Project Path="src/Microsoft.Agents.AI.DevUI/Microsoft.Agents.AI.DevUI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.DurableTask/Microsoft.Agents.AI.DurableTask.csproj" />
-    <Project Path="src/Microsoft.Agents.AI.Foundry/Microsoft.Agents.AI.Foundry.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Foundry.Hosting/Microsoft.Agents.AI.Foundry.Hosting.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Foundry/Microsoft.Agents.AI.Foundry.csproj" />
     <Project Path="src/Microsoft.Agents.AI.GitHub.Copilot/Microsoft.Agents.AI.GitHub.Copilot.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Hosting.A2A/Microsoft.Agents.AI.Hosting.A2A.csproj" />

dotnet/samples/03-workflows/Declarative/InvokeHttpRequest/InvokeHttpRequest.csproj

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
+    <InjectSharedFoundryAgents>true</InjectSharedFoundryAgents>
+    <InjectSharedWorkflowsExecution>true</InjectSharedWorkflowsExecution>
+    <InjectSharedWorkflowsSettings>true</InjectSharedWorkflowsSettings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative\Microsoft.Agents.AI.Workflows.Declarative.csproj" />
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.Workflows.Declarative.Foundry\Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="InvokeHttpRequest.yaml">
+      <CopyToOutputDirectory>Always</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
+</Project>

dotnet/samples/03-workflows/Declarative/InvokeHttpRequest/InvokeHttpRequest.yaml

@@ -0,0 +1,76 @@
+#
+# This workflow demonstrates using HttpRequestAction to call a REST API directly
+# from the workflow without going through an AI agent first.
+#
+# HttpRequestAction allows workflows to:
+# - Fetch data from external HTTP endpoints
+# - Store the parsed response in workflow variables for later use
+# - Add the response body to the conversation so a downstream agent can
+#   answer questions based on it
+#
+# This sample fetches public metadata for the dotnet/runtime repository from
+# the GitHub REST API (no authentication required) and uses an agent to
+# answer follow-up questions about it.
+#
+# Example input:
+# How many subscribers does the repository have?
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_invoke_http_request_demo
+  actions:
+
+    # Capture the original user message for input to the follow-up agent.
+    - kind: SetVariable
+      id: set_user_message
+      variable: Local.InputMessage
+      value: =System.LastMessage
+
+    # Set the repository org/name used to form the request URL.
+    - kind: SetVariable
+      id: set_repo_name
+      variable: Local.RepoName
+      value: microsoft/agent-framework
+
+    # Invoke the GitHub repo API. The response body is parsed into Local.RepoInfo
+    # and also added to the conversation (via conversationId) so the agent below
+    # can answer questions based on it.
+    - kind: HttpRequestAction
+      id: fetch_repo_info
+      conversationId: =System.ConversationId
+      method: GET
+      url: =Concatenate("https://api.github.com/repos/", Local.RepoName)
+      headers:
+        Accept: application/vnd.github+json
+        User-Agent: agent-framework-sample
+      response: Local.RepoInfo
+
+    # Display a confirmation message showing key fields from the parsed response.
+    - kind: SendMessage
+      id: show_repo_summary
+      message: "Fetched repo: visibility={Local.RepoInfo.visibility}, description={Local.RepoInfo.description}"
+
+    # Use the agent to summarize the repo using the conversation context.
+    - kind: InvokeAzureAgent
+      id: summarize_repo
+      conversationId: =System.ConversationId
+      agent:
+        name: GitHubRepoInfoAgent
+      input:
+        messages: =UserMessage("Please provide a brief summary of this GitHub repository based on the data already in the conversation.")
+      output:
+        autoSend: true
+        messages: Local.AgentResponse
+
+    # Allow the user to ask follow-up questions about the repo in a loop.
+    - kind: InvokeAzureAgent
+      id: invoke_followup
+      conversationId: =System.ConversationId
+      agent:
+        name: GitHubRepoInfoAgent
+      input:
+        messages: =Local.InputMessage
+        externalLoop:
+          when: =Upper(System.LastMessage.Text) <> "EXIT"

dotnet/samples/03-workflows/Declarative/InvokeHttpRequest/Program.cs

@@ -0,0 +1,95 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Projects;
+using Azure.AI.Projects.Agents;
+using Azure.Identity;
+using Microsoft.Agents.AI.Workflows.Declarative;
+using Microsoft.Extensions.Configuration;
+using Shared.Foundry;
+using Shared.Workflows;
+
+namespace Demo.Workflows.Declarative.InvokeHttpRequest;
+
+/// <summary>
+/// Demonstrates a workflow that uses HttpRequestAction to call a REST API
+/// directly from the workflow.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The HttpRequestAction allows workflows to issue HTTP requests and:
+/// </para>
+/// <list type="bullet">
+/// <item>Fetch data from external REST endpoints</item>
+/// <item>Store the parsed response in workflow variables</item>
+/// <item>Add the response body to the conversation so an agent can answer
+///       questions based on it</item>
+/// </list>
+/// <para>
+/// This sample fetches public metadata for the dotnet/runtime repository from
+/// the GitHub REST API (no authentication required) and uses a Foundry agent
+/// to answer follow-up questions about it. Type "EXIT" to end the conversation.
+/// </para>
+/// <para>
+/// See the README.md file in the parent folder (../README.md) for detailed
+/// information about the configuration required to run this sample.
+/// </para>
+/// </remarks>
+internal sealed class Program
+{
+    public static async Task Main(string[] args)
+    {
+        // Initialize configuration
+        IConfiguration configuration = Application.InitializeConfig();
+        Uri foundryEndpoint = new(configuration.GetValue(Application.Settings.FoundryEndpoint));
+
+        // Ensure sample agent exists in Foundry. The agent has no tools - it answers
+        // questions about the GitHub repository using only the JSON data that the
+        // HttpRequestAction adds to the conversation.
+        await CreateAgentAsync(foundryEndpoint, configuration);
+
+        // Get input from command line or console
+        string workflowInput = Application.GetInput(args);
+
+        // The default HttpRequestHandler is sufficient for this sample because the
+        // GitHub REST endpoint used here does not require authentication. For
+        // authenticated endpoints, supply a custom Func<HttpRequestInfo, ..., HttpClient?>
+        // to DefaultHttpRequestHandler so each request can be routed through a
+        // pre-configured (cached) HttpClient with the appropriate credentials.
+        await using DefaultHttpRequestHandler httpRequestHandler = new();
+
+        // Create the workflow factory with the HTTP request handler
+        WorkflowFactory workflowFactory = new("InvokeHttpRequest.yaml", foundryEndpoint)
+        {
+            HttpRequestHandler = httpRequestHandler
+        };
+
+        // Execute the workflow
+        WorkflowRunner runner = new() { UseJsonCheckpoints = true };
+        await runner.ExecuteAsync(workflowFactory.CreateWorkflow, workflowInput);
+    }
+
+    private static async Task CreateAgentAsync(Uri foundryEndpoint, IConfiguration configuration)
+    {
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        AIProjectClient aiProjectClient = new(foundryEndpoint, new DefaultAzureCredential());
+
+        await aiProjectClient.CreateAgentAsync(
+            agentName: "GitHubRepoInfoAgent",
+            agentDefinition: DefineAgent(configuration),
+            agentDescription: "Answers questions about a GitHub repository using HTTP response data in the conversation");
+    }
+
+    private static DeclarativeAgentDefinition DefineAgent(IConfiguration configuration)
+    {
+        return new DeclarativeAgentDefinition(configuration.GetValue(Application.Settings.FoundryModel))
+        {
+            Instructions =
+                """
+                Answer the user's questions about the GitHub repository using only the
+                JSON data already present in the conversation history.
+                If the answer is not contained in the conversation, say so plainly
+                rather than guessing. Be concise and helpful.
+                """
+        };
+    }
+}

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DeclarativeWorkflowOptions.cs

@@ -26,6 +26,12 @@ public sealed class DeclarativeWorkflowOptions(ResponseAgentProvider agentProvid
     /// </summary>
     public IMcpToolHandler? McpToolHandler { get; init; }
 
+    /// <summary>
+    /// Gets or sets the HTTP request handler for executing <c>HttpRequestAction</c> actions within workflows.
+    /// If not set, HTTP request actions will fail with an appropriate error message.
+    /// </summary>
+    public IHttpRequestHandler? HttpRequestHandler { get; init; }
+
     /// <summary>
     /// Defines the configuration settings for the workflow.
     /// </summary>

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/DefaultHttpRequestHandler.cs

@@ -0,0 +1,289 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Net.Http;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative;
+
+/// <summary>
+/// Default implementation of <see cref="IHttpRequestHandler"/> built on <see cref="HttpClient"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This handler supports per-request authentication via an optional <c>httpClientProvider</c> callback that
+/// returns a pre-configured <see cref="HttpClient"/> for a given request (e.g. authenticated, custom handler).
+/// When the provider returns <see langword="null"/>, or no provider is supplied, a shared internal <see cref="HttpClient"/>
+/// is used.
+/// </para>
+/// <para>
+/// The handler applies the per-request <see cref="HttpRequestInfo.Timeout"/> using a linked <see cref="CancellationTokenSource"/>
+/// so it does not mutate <see cref="HttpClient.Timeout"/> on shared instances.
+/// </para>
+/// </remarks>
+public sealed class DefaultHttpRequestHandler : IHttpRequestHandler, IAsyncDisposable
+{
+    private readonly Func<HttpRequestInfo, CancellationToken, Task<HttpClient?>>? _httpClientProvider;
+    private readonly Lazy<HttpClient> _ownedHttpClient;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DefaultHttpRequestHandler"/> class that uses an
+    /// internally owned <see cref="HttpClient"/> for all requests. The internal client is disposed
+    /// when <see cref="DisposeAsync"/> is called.
+    /// </summary>
+    public DefaultHttpRequestHandler()
+        : this(httpClientProvider: null)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DefaultHttpRequestHandler"/> class that uses the
+    /// supplied <see cref="HttpClient"/> for all requests.
+    /// </summary>
+    /// <param name="httpClient">
+    /// The <see cref="HttpClient"/> to use for all requests. The caller retains ownership of this
+    /// instance; it is not disposed by <see cref="DisposeAsync"/>.
+    /// </param>
+    /// <exception cref="ArgumentNullException"><paramref name="httpClient"/> is <see langword="null"/>.</exception>
+    public DefaultHttpRequestHandler(HttpClient httpClient)
+        : this(CreateSingleClientProvider(httpClient))
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DefaultHttpRequestHandler"/> class that selects
+    /// an <see cref="HttpClient"/> per request via a caller-supplied callback — for example, to route
+    /// different URLs through differently authenticated clients.
+    /// </summary>
+    /// <param name="httpClientProvider">
+    /// An optional callback invoked for each request. The callback receives the <see cref="HttpRequestInfo"/>
+    /// and should return a pre-configured <see cref="HttpClient"/> (e.g. with authentication or a custom
+    /// transport). Return <see langword="null"/> to fall back to the handler's shared internal
+    /// <see cref="HttpClient"/>.
+    /// </param>
+    /// <remarks>
+    /// <para>
+    /// <b>Ownership</b>: the caller is solely responsible for the lifetime of clients returned by this
+    /// callback. <see cref="DefaultHttpRequestHandler"/> will <b>not</b> dispose provider-returned
+    /// clients; only the handler's internally owned fallback client is disposed by <see cref="DisposeAsync"/>.
+    /// </para>
+    /// <para>
+    /// <b>Reuse</b>: callers are expected to cache and reuse clients (for example, keyed by base URL or
+    /// auth scope) across requests. Returning a newly allocated <see cref="HttpClient"/> on every
+    /// invocation will leak sockets and handler resources.
+    /// </para>
+    /// </remarks>
+    public DefaultHttpRequestHandler(Func<HttpRequestInfo, CancellationToken, Task<HttpClient?>>? httpClientProvider)
+    {
+        this._httpClientProvider = httpClientProvider;
+        this._ownedHttpClient = new Lazy<HttpClient>(() => new HttpClient(), LazyThreadSafetyMode.ExecutionAndPublication);
+    }
+
+    private static Func<HttpRequestInfo, CancellationToken, Task<HttpClient?>> CreateSingleClientProvider(HttpClient httpClient)
+    {
+        if (httpClient is null)
+        {
+            throw new ArgumentNullException(nameof(httpClient));
+        }
+
+        return (_, _) => Task.FromResult<HttpClient?>(httpClient);
+    }
+
+    /// <inheritdoc/>
+    public async Task<HttpRequestResult> SendAsync(HttpRequestInfo request, CancellationToken cancellationToken = default)
+    {
+        if (request is null)
+        {
+            throw new ArgumentNullException(nameof(request));
+        }
+
+        if (string.IsNullOrWhiteSpace(request.Url))
+        {
+            throw new ArgumentException("Request URL must be provided.", nameof(request));
+        }
+
+        if (string.IsNullOrWhiteSpace(request.Method))
+        {
+            throw new ArgumentException("Request method must be provided.", nameof(request));
+        }
+
+        HttpClient? providedClient = null;
+        if (this._httpClientProvider is not null)
+        {
+            providedClient = await this._httpClientProvider(request, cancellationToken).ConfigureAwait(false);
+        }
+
+        HttpClient client = providedClient ?? this._ownedHttpClient.Value;
+
+        using HttpRequestMessage httpRequest = BuildHttpRequestMessage(request);
+
+        using CancellationTokenSource? timeoutCts = request.Timeout is { } timeout && timeout > TimeSpan.Zero
+            ? CancellationTokenSource.CreateLinkedTokenSource(cancellationToken)
+            : null;
+
+        timeoutCts?.CancelAfter(request.Timeout!.Value);
+
+        CancellationToken effectiveToken = timeoutCts?.Token ?? cancellationToken;
+
+        using HttpResponseMessage httpResponse = await client
+            .SendAsync(httpRequest, HttpCompletionOption.ResponseContentRead, effectiveToken)
+            .ConfigureAwait(false);
+
+        string? body = httpResponse.Content is null
+            ? null
+#if NET
+            : await httpResponse.Content.ReadAsStringAsync(effectiveToken).ConfigureAwait(false);
+#else
+            : await httpResponse.Content.ReadAsStringAsync().ConfigureAwait(false);
+#endif
+
+        Dictionary<string, IReadOnlyList<string>> headers = new(StringComparer.OrdinalIgnoreCase);
+        AppendHeaders(headers, httpResponse.Headers);
+        if (httpResponse.Content is not null)
+        {
+            AppendHeaders(headers, httpResponse.Content.Headers);
+        }
+
+        return new HttpRequestResult
+        {
+            StatusCode = (int)httpResponse.StatusCode,
+            IsSuccessStatusCode = httpResponse.IsSuccessStatusCode,
+            Body = body,
+            Headers = headers,
+        };
+    }
+
+    /// <inheritdoc/>
+    public ValueTask DisposeAsync()
+    {
+        if (this._ownedHttpClient.IsValueCreated)
+        {
+            this._ownedHttpClient.Value.Dispose();
+        }
+
+        return default;
+    }
+
+    private static HttpRequestMessage BuildHttpRequestMessage(HttpRequestInfo request)
+    {
+        HttpMethod method = ResolveMethod(request.Method);
+        string requestUri = ResolveRequestUri(request);
+        HttpRequestMessage httpRequest = new(method, requestUri);
+
+        if (request.Body is not null)
+        {
+            string contentType = string.IsNullOrWhiteSpace(request.BodyContentType)
+                ? "text/plain"
+                : request.BodyContentType!;
+
+            httpRequest.Content = new StringContent(request.Body, Encoding.UTF8);
+            // Replace the default content-type header (including charset) with the declared type.
+            httpRequest.Content.Headers.Remove("Content-Type");
+            httpRequest.Content.Headers.TryAddWithoutValidation("Content-Type", contentType);
+        }
+
+        if (request.Headers is not null)
+        {
+            foreach (KeyValuePair<string, string> header in request.Headers)
+            {
+                if (string.IsNullOrEmpty(header.Key))
+                {
+                    continue;
+                }
+
+                // Content-* headers belong on HttpContent; all others belong on the request.
+                if (header.Key.StartsWith("Content-", StringComparison.OrdinalIgnoreCase) && httpRequest.Content is not null)
+                {
+                    httpRequest.Content.Headers.Remove(header.Key);
+                    httpRequest.Content.Headers.TryAddWithoutValidation(header.Key, header.Value);
+                    continue;
+                }
+
+                if (!httpRequest.Headers.TryAddWithoutValidation(header.Key, header.Value))
+                {
+                    httpRequest.Content?.Headers.TryAddWithoutValidation(header.Key, header.Value);
+                }
+            }
+        }
+
+        return httpRequest;
+    }
+
+    private static HttpMethod ResolveMethod(string method)
+    {
+        string normalized = method.Trim().ToUpperInvariant();
+        return normalized switch
+        {
+            "GET" => HttpMethod.Get,
+            "POST" => HttpMethod.Post,
+            "PUT" => HttpMethod.Put,
+            "DELETE" => HttpMethod.Delete,
+#if NET
+            "PATCH" => HttpMethod.Patch,
+#else
+            "PATCH" => new HttpMethod("PATCH"),
+#endif
+            _ => new HttpMethod(normalized),
+        };
+    }
+
+    private static string ResolveRequestUri(HttpRequestInfo request)
+    {
+        string baseUrl = request.Url;
+        if (request.QueryParameters is null || request.QueryParameters.Count == 0)
+        {
+            return baseUrl;
+        }
+
+        StringBuilder queryBuilder = new();
+        foreach (KeyValuePair<string, string> parameter in request.QueryParameters)
+        {
+            if (string.IsNullOrEmpty(parameter.Key))
+            {
+                continue;
+            }
+
+            if (queryBuilder.Length > 0)
+            {
+                queryBuilder.Append('&');
+            }
+
+            queryBuilder.Append(Uri.EscapeDataString(parameter.Key))
+                .Append('=')
+                .Append(Uri.EscapeDataString(parameter.Value ?? string.Empty));
+        }
+
+        if (queryBuilder.Length == 0)
+        {
+            return baseUrl;
+        }
+
+        char separator = baseUrl.Contains('?') ? '&' : '?';
+        return string.Concat(baseUrl, separator.ToString(), queryBuilder.ToString());
+    }
+
+    private static void AppendHeaders(
+        Dictionary<string, IReadOnlyList<string>> target,
+        System.Net.Http.Headers.HttpHeaders source)
+    {
+        foreach (KeyValuePair<string, IEnumerable<string>> header in source)
+        {
+            string[] values = header.Value.ToArray();
+
+            if (target.TryGetValue(header.Key, out IReadOnlyList<string>? existing))
+            {
+                List<string> combined = new(existing);
+                combined.AddRange(values);
+                target[header.Key] = combined;
+            }
+            else
+            {
+                target[header.Key] = values;
+            }
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Extensions/ChatMessageExtensions.cs

@@ -16,6 +16,60 @@ internal static class ChatMessageExtensions
     public static RecordValue ToRecord(this ChatMessage message) =>
         FormulaValue.NewRecordFromFields(message.GetMessageFields());
 
+    /// <summary>
+    /// Merges the user-authored <paramref name="input"/> with the round-tripped
+    /// <paramref name="inputMessage"/> returned by <c>AgentProvider.CreateMessageAsync</c>
+    /// to produce the value stored in <c>System.LastMessage</c>.
+    /// </summary>
+    /// <remarks>
+    /// The agent service often strips or alters <see cref="TextContent"/> on round-trip,
+    /// while replacing inline media (<see cref="DataContent"/>, <see cref="UriContent"/>)
+    /// with server-side references (typically <see cref="HostedFileContent"/>).
+    /// We want both: the original text (so <c>=System.LastMessage.Text</c> works) and
+    /// the server's media references (so subsequent actions don't re-upload large blobs).
+    /// <para>
+    /// Strategy: keep <paramref name="inputMessage"/> as the base — it has the server-generated
+    /// <see cref="ChatMessage.MessageId"/> and any provider-augmented metadata, and is forward-
+    /// compatible with new properties added on <see cref="ChatMessage"/> in the abstractions
+    /// layer. Only the <see cref="ChatMessage.Contents"/> list is mutated to substitute
+    /// original <see cref="TextContent"/> items in place (and append any extras the round-trip
+    /// dropped). Non-text content items returned by the service are left untouched so
+    /// server-side references survive.
+    /// </para>
+    /// </remarks>
+    public static ChatMessage MergeForLastMessage(this ChatMessage input, ChatMessage? inputMessage)
+    {
+        if (inputMessage is null)
+        {
+            return input;
+        }
+
+        // Build a queue of the original text items, in order. Fall back to ChatMessage.Text
+        // if the input has no explicit TextContent entries.
+        Queue<TextContent> originalTexts = new(input.Contents.OfType<TextContent>());
+        if (originalTexts.Count == 0 && !string.IsNullOrEmpty(input.Text))
+        {
+            originalTexts.Enqueue(new TextContent(input.Text));
+        }
+
+        // Replace TextContent items in inputMessage.Contents with the originals, in order.
+        for (int i = 0; i < inputMessage.Contents.Count && originalTexts.Count > 0; i++)
+        {
+            if (inputMessage.Contents[i] is TextContent)
+            {
+                inputMessage.Contents[i] = originalTexts.Dequeue();
+            }
+        }
+
+        // Append any remaining original text items that the round-trip dropped entirely.
+        while (originalTexts.Count > 0)
+        {
+            inputMessage.Contents.Add(originalTexts.Dequeue());
+        }
+
+        return inputMessage;
+    }
+
     public static TableValue ToTable(this IEnumerable<ChatMessage> messages) =>
         FormulaValue.NewTable(TypeSchema.Message.RecordType, messages.Select(message => message.ToRecord()));
 

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/IHttpRequestHandler.cs

@@ -0,0 +1,103 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative;
+
+/// <summary>
+/// Defines the contract for executing HTTP requests emitted by <c>HttpRequestAction</c> within declarative workflows.
+/// </summary>
+/// <remarks>
+/// This interface allows the HTTP request dispatch to be abstracted, enabling different implementations
+/// for local development, hosted workflows, authenticated scenarios, and testing.
+/// </remarks>
+public interface IHttpRequestHandler
+{
+    /// <summary>
+    /// Sends an HTTP request and returns the response.
+    /// </summary>
+    /// <param name="request">The HTTP request to send.</param>
+    /// <param name="cancellationToken">A token to observe cancellation.</param>
+    /// <returns>The <see cref="HttpRequestResult"/> describing the HTTP response.</returns>
+    Task<HttpRequestResult> SendAsync(
+        HttpRequestInfo request,
+        CancellationToken cancellationToken = default);
+}
+
+/// <summary>
+/// Describes an HTTP request to be sent by an <see cref="IHttpRequestHandler"/>.
+/// </summary>
+[SuppressMessage("Design", "CA1056:URI-like properties should not be strings", Justification = "URL is carried as a string to preserve the declarative expression result and to avoid forcing handler implementations to construct a Uri eagerly.")]
+public sealed class HttpRequestInfo
+{
+    /// <summary>
+    /// Gets the HTTP method to use (GET, POST, PUT, PATCH, DELETE).
+    /// </summary>
+    public string Method { get; init; } = "GET";
+
+    /// <summary>
+    /// Gets the absolute URL to send the request to.
+    /// </summary>
+    public string Url { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Gets the headers to include on the request, excluding the <c>Content-Type</c> header (which is supplied via <see cref="BodyContentType"/>).
+    /// </summary>
+    public IReadOnlyDictionary<string, string>? Headers { get; init; }
+
+    /// <summary>
+    /// Gets the <c>Content-Type</c> of the request body, or <see langword="null"/> if no body is sent.
+    /// </summary>
+    public string? BodyContentType { get; init; }
+
+    /// <summary>
+    /// Gets the serialized request body, or <see langword="null"/> if no body is sent.
+    /// </summary>
+    public string? Body { get; init; }
+
+    /// <summary>
+    /// Gets the maximum amount of time to wait for the request to complete, or <see langword="null"/> to use the handler default.
+    /// </summary>
+    public TimeSpan? Timeout { get; init; }
+
+    /// <summary>
+    /// Gets the query parameters to append to the request URL, with values already formatted as strings.
+    /// </summary>
+    public IReadOnlyDictionary<string, string>? QueryParameters { get; init; }
+
+    /// <summary>
+    /// Gets the name of the declared remote connection, or <see langword="null"/> if no connection is declared.
+    /// This maps to the Foundry project connection Id and is only used when running in foundry service.
+    /// </summary>
+    public string? ConnectionName { get; init; }
+}
+
+/// <summary>
+/// Represents the result of an HTTP request executed by an <see cref="IHttpRequestHandler"/>.
+/// </summary>
+public sealed class HttpRequestResult
+{
+    /// <summary>
+    /// Gets the HTTP status code returned by the server.
+    /// </summary>
+    public int StatusCode { get; init; }
+
+    /// <summary>
+    /// Gets a value indicating whether the status code is in the range 200-299.
+    /// </summary>
+    public bool IsSuccessStatusCode { get; init; }
+
+    /// <summary>
+    /// Gets the response body, or <see langword="null"/> if no body was returned.
+    /// </summary>
+    public string? Body { get; init; }
+
+    /// <summary>
+    /// Gets the response headers keyed by header name. Each header may have multiple values.
+    /// </summary>
+    public IReadOnlyDictionary<string, IReadOnlyList<string>>? Headers { get; init; }
+}

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/DeclarativeWorkflowExecutor.cs

@@ -43,7 +43,11 @@ internal sealed class DeclarativeWorkflowExecutor<TInput>(
         await declarativeContext.QueueConversationUpdateAsync(conversationId, isExternal: true, cancellationToken).ConfigureAwait(false);
 
         ChatMessage inputMessage = await options.AgentProvider.CreateMessageAsync(conversationId, input, cancellationToken).ConfigureAwait(false);
-        await declarativeContext.SetLastMessageAsync(inputMessage).ConfigureAwait(false);
+
+        // Use the original input for System.LastMessage to ensure Text is preserved (the
+        // service may strip text on round-trip), but substitute server-side media references
+        // (e.g., HostedFileContent) so subsequent actions don't re-upload large blobs.
+        await declarativeContext.SetLastMessageAsync(input.MergeForLastMessage(inputMessage)).ConfigureAwait(false);
 
         await context.SendResultMessageAsync(this.Id, cancellationToken).ConfigureAwait(false);
     }

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Interpreter/WorkflowActionVisitor.cs

@@ -529,6 +529,18 @@ internal sealed class WorkflowActionVisitor : DialogActionVisitor
         this._workflowModel.AddNode(new DelegateActionExecutor(postId, this._workflowState, action.CompleteAsync), action.ParentId);
     }
 
+    protected override void Visit(HttpRequestAction item)
+    {
+        this.Trace(item);
+
+        if (this._workflowOptions.HttpRequestHandler is null)
+        {
+            throw new DeclarativeModelException("HTTP request handler not configured. Set HttpRequestHandler in DeclarativeWorkflowOptions to use HttpRequestAction actions.");
+        }
+
+        this.ContinueWith(new HttpRequestExecutor(item, this._workflowOptions.HttpRequestHandler, this._workflowOptions.AgentProvider, this._workflowState));
+    }
+
     #region Not supported
 
     protected override void Visit(AnswerQuestionWithAI item) => this.NotSupported(item);
@@ -573,8 +585,6 @@ internal sealed class WorkflowActionVisitor : DialogActionVisitor
 
     protected override void Visit(GetConversationMembers item) => this.NotSupported(item);
 
-    protected override void Visit(HttpRequestAction item) => this.NotSupported(item);
-
     protected override void Visit(RecognizeIntent item) => this.NotSupported(item);
 
     protected override void Visit(TransferConversation item) => this.NotSupported(item);

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Kit/RootExecutor.cs

@@ -58,7 +58,6 @@ public abstract class RootExecutor<TInput> : Executor<TInput>, IResettableExecut
     public override async ValueTask HandleAsync(TInput message, IWorkflowContext context, CancellationToken cancellationToken)
     {
         DeclarativeWorkflowContext declarativeContext = new(context, this._state);
-        await this.ExecuteAsync(message, declarativeContext, cancellationToken).ConfigureAwait(false);
 
         ChatMessage input = (this._inputTransform ?? DefaultInputTransform).Invoke(message);
 
@@ -69,7 +68,13 @@ public abstract class RootExecutor<TInput> : Executor<TInput>, IResettableExecut
         await declarativeContext.QueueConversationUpdateAsync(this._conversationId, isExternal: true, cancellationToken).ConfigureAwait(false);
 
         ChatMessage inputMessage = await this._agentProvider.CreateMessageAsync(this._conversationId, input, cancellationToken).ConfigureAwait(false);
-        await declarativeContext.SetLastMessageAsync(inputMessage).ConfigureAwait(false);
+
+        // Use the original input for System.LastMessage to ensure Text is preserved (the
+        // service may strip text on round-trip), but substitute server-side media references
+        // (e.g., HostedFileContent) so subsequent actions don't re-upload large blobs.
+        await declarativeContext.SetLastMessageAsync(input.MergeForLastMessage(inputMessage)).ConfigureAwait(false);
+
+        await this.ExecuteAsync(message, declarativeContext, cancellationToken).ConfigureAwait(false);
 
         await declarativeContext.SendResultMessageAsync(this.Id, cancellationToken).ConfigureAwait(false);
     }

dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/ObjectModel/HttpRequestExecutor.cs

@@ -0,0 +1,346 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.Declarative.Extensions;
+using Microsoft.Agents.AI.Workflows.Declarative.Interpreter;
+using Microsoft.Agents.AI.Workflows.Declarative.Kit;
+using Microsoft.Agents.AI.Workflows.Declarative.PowerFx;
+using Microsoft.Agents.ObjectModel;
+using Microsoft.Extensions.AI;
+using Microsoft.PowerFx.Types;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
+
+/// <summary>
+/// Executor for the <see cref="HttpRequestAction"/> action.
+/// Dispatches the request through the configured <see cref="IHttpRequestHandler"/> and assigns
+/// the response body and headers to the declared property paths.
+/// </summary>
+internal sealed class HttpRequestExecutor(
+    HttpRequestAction model,
+    IHttpRequestHandler httpRequestHandler,
+    ResponseAgentProvider agentProvider,
+    WorkflowFormulaState state) :
+    DeclarativeActionExecutor<HttpRequestAction>(model, state)
+{
+    /// <inheritdoc/>
+    protected override async ValueTask<object?> ExecuteAsync(IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        string method = this.GetMethod();
+        string url = this.GetUrl();
+        Dictionary<string, string>? headers = this.GetHeaders();
+        Dictionary<string, string>? queryParameters = this.GetQueryParameters();
+        (string? body, string? contentType) = this.GetBody();
+        TimeSpan? timeout = this.GetTimeout();
+        string? conversationId = this.GetConversationId();
+        string? connectionName = this.GetConnectionName();
+
+        HttpRequestInfo requestInfo = new()
+        {
+            Method = method,
+            Url = url,
+            Headers = headers,
+            QueryParameters = queryParameters,
+            Body = body,
+            BodyContentType = contentType,
+            Timeout = timeout,
+            ConnectionName = connectionName,
+        };
+
+        HttpRequestResult result;
+        try
+        {
+            result = await httpRequestHandler.SendAsync(requestInfo, cancellationToken).ConfigureAwait(false);
+        }
+        catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested)
+        {
+            throw this.Exception($"HTTP request to '{url}' timed out.");
+        }
+        catch (Exception exception) when (exception is not DeclarativeActionException)
+        {
+            throw this.Exception($"HTTP request to '{url}' failed: {exception.Message}", exception);
+        }
+
+        if (result.IsSuccessStatusCode)
+        {
+            await this.AssignResponseAsync(context, result.Body).ConfigureAwait(false);
+            await this.AssignResponseHeadersAsync(context, result.Headers).ConfigureAwait(false);
+            await this.AddResponseToConversationAsync(conversationId, result.Body, cancellationToken).ConfigureAwait(false);
+            return default;
+        }
+
+        // Non-success status code - throw.
+        // Also publish response headers for diagnostic purposes.
+        await this.AssignResponseHeadersAsync(context, result.Headers).ConfigureAwait(false);
+
+        string bodyPreview = FormatBodyForDiagnostics(result.Body);
+        string message = bodyPreview.Length == 0
+            ? $"HTTP request to '{url}' failed with status code {result.StatusCode}."
+            : $"HTTP request to '{url}' failed with status code {result.StatusCode}. Body: '{bodyPreview}'";
+
+        throw this.Exception(message);
+    }
+
+    // Response bodies can echo secrets (tokens, PII) and may be very large (multi-MB HTML error pages).
+    // Exception messages are often logged and persisted, so we clip the body to bound both exposure
+    // and message size. Full bodies are still available via the success path (assigned to Response).
+    private const int MaxBodyDiagnosticLength = 256;
+    private const string BodyTruncationSuffix = " \u2026 [truncated]";
+
+    private static string FormatBodyForDiagnostics(string? body)
+    {
+        if (string.IsNullOrEmpty(body))
+        {
+            return string.Empty;
+        }
+
+        int sourceLen = body!.Length;
+        bool truncated = sourceLen > MaxBodyDiagnosticLength;
+        int copyLen = truncated ? MaxBodyDiagnosticLength : sourceLen;
+        int finalLen = copyLen + (truncated ? BodyTruncationSuffix.Length : 0);
+
+        // Size the buffer for the final string so we only allocate once for the chars
+        // and once for the string itself. For a 10 KB error body we touch 256 chars instead of 10,000.
+        char[] buffer = new char[finalLen];
+        for (int i = 0; i < copyLen; i++)
+        {
+            char c = body[i];
+            buffer[i] = c is '\r' or '\n' or '\t' ? ' ' : c;
+        }
+
+        if (truncated)
+        {
+            BodyTruncationSuffix.CopyTo(0, buffer, copyLen, BodyTruncationSuffix.Length);
+        }
+
+        return new string(buffer);
+    }
+
+    private async ValueTask AddResponseToConversationAsync(string? conversationId, string? responseBody, CancellationToken cancellationToken)
+    {
+        if (conversationId is null || string.IsNullOrEmpty(responseBody))
+        {
+            return;
+        }
+
+        ChatMessage message = new(ChatRole.Assistant, responseBody);
+        await agentProvider.CreateMessageAsync(conversationId, message, cancellationToken).ConfigureAwait(false);
+    }
+
+    private async ValueTask AssignResponseAsync(IWorkflowContext context, string? responseBody)
+    {
+        if (this.Model.Response is not { Path: { } responsePath })
+        {
+            return;
+        }
+
+        await this.AssignAsync(responsePath, ParseResponseBody(responseBody), context).ConfigureAwait(false);
+    }
+
+    private async ValueTask AssignResponseHeadersAsync(IWorkflowContext context, IReadOnlyDictionary<string, IReadOnlyList<string>>? responseHeaders)
+    {
+        if (this.Model.ResponseHeaders is not { Path: { } headersPath })
+        {
+            return;
+        }
+
+        if (responseHeaders is null || responseHeaders.Count == 0)
+        {
+            await this.AssignAsync(headersPath, FormulaValue.NewBlank(), context).ConfigureAwait(false);
+            return;
+        }
+
+        // Flatten multi-value headers by joining with commas (standard HTTP header folding).
+        Dictionary<string, object?> flattened = new(StringComparer.OrdinalIgnoreCase);
+        foreach (KeyValuePair<string, IReadOnlyList<string>> header in responseHeaders)
+        {
+            flattened[header.Key] = string.Join(",", header.Value);
+        }
+
+        await this.AssignAsync(headersPath, flattened.ToFormula(), context).ConfigureAwait(false);
+    }
+
+    private static FormulaValue ParseResponseBody(string? responseBody)
+    {
+        if (string.IsNullOrEmpty(responseBody))
+        {
+            return FormulaValue.NewBlank();
+        }
+
+        // Attempt to parse as JSON so records/tables are exposed naturally to the workflow.
+        try
+        {
+            using JsonDocument jsonDocument = JsonDocument.Parse(responseBody);
+
+            object? parsedValue = jsonDocument.RootElement.ValueKind switch
+            {
+                JsonValueKind.Object => jsonDocument.ParseRecord(VariableType.RecordType),
+                JsonValueKind.Array => jsonDocument.ParseList(jsonDocument.RootElement.GetListTypeFromJson()),
+                JsonValueKind.String => jsonDocument.RootElement.GetString(),
+                JsonValueKind.Number => jsonDocument.RootElement.TryGetInt64(out long l)
+                    ? l
+                    : jsonDocument.RootElement.GetDouble(),
+                JsonValueKind.True => true,
+                JsonValueKind.False => false,
+                JsonValueKind.Null => null,
+                _ => responseBody,
+            };
+
+            return parsedValue.ToFormula();
+        }
+        catch (JsonException)
+        {
+            // Not valid JSON — return the raw string.
+            return FormulaValue.New(responseBody);
+        }
+    }
+
+    private string GetMethod()
+    {
+        EnumExpression<HttpMethodTypeWrapper>? methodExpression = this.Model.Method;
+        if (methodExpression is null)
+        {
+            return "GET";
+        }
+
+        HttpMethodTypeWrapper wrapper = this.Evaluator.GetValue(methodExpression).Value;
+        return !string.IsNullOrEmpty(wrapper.UnknownValue) ? wrapper.UnknownValue! : wrapper.Value.ToString().ToUpperInvariant();
+    }
+
+    private string GetUrl() =>
+        this.Evaluator.GetValue(
+            Throw.IfNull(
+                this.Model.Url,
+                $"{nameof(this.Model)}.{nameof(this.Model.Url)}")).Value;
+
+    private Dictionary<string, string>? GetHeaders()
+    {
+        if (this.Model.Headers is null || this.Model.Headers.Count == 0)
+        {
+            return null;
+        }
+
+        Dictionary<string, string> result = new(StringComparer.OrdinalIgnoreCase);
+        foreach (KeyValuePair<string, StringExpression> header in this.Model.Headers)
+        {
+            string value = this.Evaluator.GetValue(header.Value).Value;
+            if (!string.IsNullOrEmpty(value))
+            {
+                result[header.Key] = value;
+            }
+        }
+
+        return result.Count == 0 ? null : result;
+    }
+
+    private (string? Body, string? ContentType) GetBody()
+    {
+        switch (this.Model.Body)
+        {
+            case null:
+            case NoRequestContent:
+                return (null, null);
+
+            case JsonRequestContent jsonContent when jsonContent.Content is not null:
+            {
+                FormulaValue formula = this.Evaluator.GetValue(jsonContent.Content).Value.ToFormula();
+                string json = formula.ToJson().ToJsonString();
+                return (json, "application/json");
+            }
+
+            case RawRequestContent rawContent:
+            {
+                string? content = rawContent.Content is null
+                        ? null
+                        : this.Evaluator.GetValue(rawContent.Content).Value;
+
+                string? contentType = rawContent.ContentType is null
+                        ? null
+                        : this.Evaluator.GetValue(rawContent.ContentType).Value;
+
+                return (content, string.IsNullOrEmpty(contentType) ? null : contentType);
+            }
+
+            default:
+                return (null, null);
+        }
+    }
+
+    private TimeSpan? GetTimeout()
+    {
+        if (this.Model.RequestTimeoutInMilliseconds is null || this.Model.RequestTimeoutInMillisecondsIsDefaultValue)
+        {
+            return null;
+        }
+
+        long value = this.Evaluator.GetValue(this.Model.RequestTimeoutInMilliseconds).Value;
+        return value > 0 ? TimeSpan.FromMilliseconds(value) : null;
+    }
+
+    private Dictionary<string, string>? GetQueryParameters()
+    {
+        if (this.Model.QueryParameters is null || this.Model.QueryParameters.Count == 0)
+        {
+            return null;
+        }
+
+        Dictionary<string, string> result = new(StringComparer.Ordinal);
+        foreach (KeyValuePair<string, ValueExpression> parameter in this.Model.QueryParameters)
+        {
+            if (string.IsNullOrEmpty(parameter.Key) || parameter.Value is null)
+            {
+                continue;
+            }
+
+            object? rawValue = this.Evaluator.GetValue(parameter.Value).Value.ToObject();
+            string? formatted = FormatQueryValue(rawValue);
+            if (formatted is not null)
+            {
+                result[parameter.Key] = formatted;
+            }
+        }
+
+        return result.Count == 0 ? null : result;
+    }
+
+    private static string? FormatQueryValue(object? value) =>
+        value switch
+        {
+            null => null,
+            string s => s,
+            bool b => b ? "true" : "false",
+            IFormattable formattable => formattable.ToString(null, System.Globalization.CultureInfo.InvariantCulture),
+            _ => value.ToString(),
+        };
+
+    private string? GetConversationId()
+    {
+        if (this.Model.ConversationId is null)
+        {
+            return null;
+        }
+
+        string value = this.Evaluator.GetValue(this.Model.ConversationId).Value;
+        return value.Length == 0 ? null : value;
+    }
+
+    private string? GetConnectionName()
+    {
+        RemoteConnection? connection = this.Model.Connection;
+        if (connection is null)
+        {
+            return null;
+        }
+
+        string? name = connection.Name is null
+            ? null
+            : this.Evaluator.GetValue(connection.Name).Value;
+
+        return string.IsNullOrEmpty(name) ? null : name;
+    }
+}

dotnet/src/Shared/Workflows/Execution/WorkflowFactory.cs

@@ -25,6 +25,9 @@ internal sealed class WorkflowFactory(string workflowFile, Uri foundryEndpoint)
     // Assign to provide MCP tool capabilities
     public IMcpToolHandler? McpToolHandler { get; init; }
 
+    // Assign to enable HttpRequestAction support
+    public IHttpRequestHandler? HttpRequestHandler { get; init; }
+
     /// <summary>
     /// Create the workflow from the declarative YAML.  Includes definition of the
     /// <see cref="DeclarativeWorkflowOptions" /> and the associated <see cref="ResponseAgentProvider"/>.
@@ -46,6 +49,7 @@ internal sealed class WorkflowFactory(string workflowFile, Uri foundryEndpoint)
                 ConversationId = this.ConversationId,
                 LoggerFactory = this.LoggerFactory,
                 McpToolHandler = this.McpToolHandler,
+                HttpRequestHandler = this.HttpRequestHandler,
             };
 
         string workflowPath = Path.Combine(AppContext.BaseDirectory, workflowFile);

dotnet/src/Shared/Workflows/Execution/WorkflowRunner.cs

@@ -162,7 +162,10 @@ internal sealed class WorkflowRunner
 
                 case RequestInfoEvent requestInfo:
                     Debug.WriteLine($"REQUEST #{requestInfo.Request.RequestId}");
-                    externalResponse = requestInfo.Request;
+                    if (response is null || !string.Equals(requestInfo.Request.RequestId, response.RequestId, StringComparison.Ordinal))
+                    {
+                        externalResponse = requestInfo.Request;
+                    }
                     break;
 
                 case ConversationUpdateEvent invokeEvent:

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests/Framework/IntegrationTest.cs

@@ -60,10 +60,20 @@ public abstract class IntegrationTest : IDisposable
 
     protected async ValueTask<DeclarativeWorkflowOptions> CreateOptionsAsync(bool externalConversation = false, params IEnumerable<AIFunction> functionTools)
     {
-        return await this.CreateOptionsAsync(externalConversation, mcpToolProvider: null, functionTools).ConfigureAwait(false);
+        return await this.CreateOptionsAsync(externalConversation, mcpToolProvider: null, httpRequestHandler: null, functionTools).ConfigureAwait(false);
     }
 
     protected async ValueTask<DeclarativeWorkflowOptions> CreateOptionsAsync(bool externalConversation, IMcpToolHandler? mcpToolProvider, params IEnumerable<AIFunction> functionTools)
+    {
+        return await this.CreateOptionsAsync(externalConversation, mcpToolProvider, httpRequestHandler: null, functionTools).ConfigureAwait(false);
+    }
+
+    protected async ValueTask<DeclarativeWorkflowOptions> CreateOptionsAsync(bool externalConversation, IHttpRequestHandler? httpRequestHandler, params IEnumerable<AIFunction> functionTools)
+    {
+        return await this.CreateOptionsAsync(externalConversation, mcpToolProvider: null, httpRequestHandler, functionTools).ConfigureAwait(false);
+    }
+
+    protected async ValueTask<DeclarativeWorkflowOptions> CreateOptionsAsync(bool externalConversation, IMcpToolHandler? mcpToolProvider, IHttpRequestHandler? httpRequestHandler, params IEnumerable<AIFunction> functionTools)
     {
         AzureAgentProvider agentProvider =
             new(this.TestEndpoint, TestAzureCliCredentials.CreateAzureCliCredential())
@@ -82,7 +92,8 @@ public abstract class IntegrationTest : IDisposable
             {
                 ConversationId = conversationId,
                 LoggerFactory = this.Output,
-                McpToolHandler = mcpToolProvider
+                McpToolHandler = mcpToolProvider,
+                HttpRequestHandler = httpRequestHandler,
             };
     }
 

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests/InvokeToolWorkflowTest.cs

@@ -45,6 +45,15 @@ public sealed class InvokeToolWorkflowTest(ITestOutputHelper output) : Integrati
 
     #endregion
 
+    #region InvokeHttpRequest Tests
+
+    [RetryTheory(3, 5000)]
+    [InlineData("HttpRequest.yaml", "visibility: public")]
+    public Task ValidateHttpRequestAsync(string workflowFileName, string? expectedResultContains) =>
+        this.RunHttpRequestTestAsync(workflowFileName, expectedResultContains);
+
+    #endregion
+
     #region InvokeFunctionTool Test Helpers
 
     /// <summary>
@@ -250,6 +259,40 @@ public sealed class InvokeToolWorkflowTest(ITestOutputHelper output) : Integrati
 
     #endregion
 
+    #region InvokeHttpRequest Test Helpers
+
+    /// <summary>
+    /// Runs an HttpRequestAction workflow test with the specified configuration.
+    /// </summary>
+    private async Task RunHttpRequestTestAsync(
+        string workflowFileName,
+        string? expectedResultContains = null)
+    {
+        // Arrange
+        string workflowPath = GetWorkflowPath(workflowFileName);
+        await using DefaultHttpRequestHandler httpRequestHandler = new();
+        DeclarativeWorkflowOptions workflowOptions = await this.CreateOptionsAsync(
+            externalConversation: false,
+            httpRequestHandler: httpRequestHandler);
+
+        Workflow workflow = DeclarativeWorkflowBuilder.Build<string>(workflowPath, workflowOptions);
+        WorkflowHarness harness = new(workflow, runId: Path.GetFileNameWithoutExtension(workflowPath));
+
+        // Act
+        WorkflowEvents workflowEvents = await harness.RunWorkflowAsync("start").ConfigureAwait(false);
+
+        // Assert - Verify executor and action events
+        AssertWorkflowEventsEmitted(workflowEvents);
+
+        // Assert - Verify expected result if specified
+        if (expectedResultContains is not null)
+        {
+            AssertResultContains(workflowEvents, expectedResultContains);
+        }
+    }
+
+    #endregion
+
     #region Shared Helpers
 
     private static void AssertWorkflowEventsEmitted(WorkflowEvents workflowEvents)

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.IntegrationTests/Workflows/HttpRequest.yaml

@@ -0,0 +1,32 @@
+#
+# This workflow tests invoking HttpRequestAction end-to-end.
+# Uses the public GitHub API (unauthenticated) to fetch repo metadata.
+#
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: workflow_http_request_test
+  actions:
+
+    # Set the repo owner used to form the request URL.
+    - kind: SetVariable
+      id: set_repo_owner
+      variable: Local.RepoOwner
+      value: dotnet
+
+    # Invoke the GitHub repo API.
+    - kind: HttpRequestAction
+      id: fetch_repo_info
+      conversationId: =System.ConversationId
+      method: GET
+      url: =Concatenate("https://api.github.com/repos/", Local.RepoOwner, "/runtime")
+      headers:
+        Accept: application/vnd.github+json
+        User-Agent: agent-framework-integration-test
+      response: Local.RepoInfo
+
+    # Surface the Repo visibility field from the parsed JSON response.
+    - kind: SendMessage
+      id: show_visibility
+      message: "visibility: {Local.RepoInfo.visibility}"

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

@@ -181,6 +181,7 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow
     [InlineData("ResetVariable.yaml", 2, "clear_var")]
     [InlineData("MixedScopes.yaml", 2, "activity_input")]
     [InlineData("CaseInsensitive.yaml", 6, "end_when_match")]
+    [InlineData("HttpRequest.yaml", 1, "http_request")]
     public async Task ExecuteActionAsync(string workflowFile, int expectedCount, string expectedId)
     {
         await this.RunWorkflowAsync(workflowFile);
@@ -200,7 +201,6 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow
     [InlineData(typeof(EmitEvent.Builder))]
     [InlineData(typeof(GetActivityMembers.Builder))]
     [InlineData(typeof(GetConversationMembers.Builder))]
-    [InlineData(typeof(HttpRequestAction.Builder))]
     [InlineData(typeof(InvokeAIBuilderModelAction.Builder))]
     [InlineData(typeof(InvokeConnectorAction.Builder))]
     [InlineData(typeof(InvokeCustomModelAction.Builder))]
@@ -266,6 +266,7 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow
     [InlineData("SendActivity.yaml", "activity_input")]
     [InlineData("SetVariable.yaml", "set_var")]
     [InlineData("SetTextVariable.yaml", "set_text")]
+    [InlineData("HttpRequest.yaml", "http_request")]
     public async Task CancelRunAsync(string workflowPath, string expectedExecutedId)
     {
         // Arrange
@@ -374,7 +375,12 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow
     {
         using StreamReader yamlReader = File.OpenText(Path.Combine("Workflows", workflowPath));
         Mock<ResponseAgentProvider> mockAgentProvider = CreateMockProvider($"{workflowInput}");
-        DeclarativeWorkflowOptions workflowContext = new(mockAgentProvider.Object) { LoggerFactory = this.Output };
+        DeclarativeWorkflowOptions workflowContext =
+            new(mockAgentProvider.Object)
+            {
+                LoggerFactory = this.Output,
+                HttpRequestHandler = CreateMockHttpRequestHandler().Object,
+            };
         return DeclarativeWorkflowBuilder.Build<TInput>(yamlReader, workflowContext);
     }
 
@@ -385,4 +391,18 @@ public sealed class DeclarativeWorkflowTest(ITestOutputHelper output) : Workflow
         mockAgentProvider.Setup(provider => provider.CreateMessageAsync(It.IsAny<string>(), It.IsAny<ChatMessage>(), It.IsAny<CancellationToken>())).Returns(Task.FromResult(new ChatMessage(ChatRole.Assistant, input)));
         return mockAgentProvider;
     }
+
+    private static Mock<IHttpRequestHandler> CreateMockHttpRequestHandler()
+    {
+        Mock<IHttpRequestHandler> mockHandler = new(MockBehavior.Loose);
+        mockHandler
+            .Setup(handler => handler.SendAsync(It.IsAny<HttpRequestInfo>(), It.IsAny<CancellationToken>()))
+            .Returns(() => Task.FromResult(new HttpRequestResult
+            {
+                StatusCode = 200,
+                IsSuccessStatusCode = true,
+                Body = "{\"ok\":true}",
+            }));
+        return mockHandler;
+    }
 }

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

@@ -0,0 +1,510 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Net;
+using System.Net.Http;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using FluentAssertions;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative.UnitTests;
+
+/// <summary>
+/// Unit tests for <see cref="DefaultHttpRequestHandler"/>.
+/// </summary>
+public sealed class DefaultHttpRequestHandlerTests
+{
+    private static readonly string[] s_setCookieValues = ["a=1", "b=2"];
+
+    private const string TestUrl = "https://api.example.test/resource";
+
+    #region Constructor Tests
+
+    [Fact]
+    public async Task ConstructorWithNoParametersCreatesInstanceAsync()
+    {
+        // Act
+        await using DefaultHttpRequestHandler handler = new();
+
+        // Assert
+        handler.Should().NotBeNull();
+    }
+
+    [Fact]
+    public async Task ConstructorWithNullProviderCreatesInstanceAsync()
+    {
+        // Act
+        await using DefaultHttpRequestHandler handler = new(httpClientProvider: null);
+
+        // Assert
+        handler.Should().NotBeNull();
+    }
+
+    [Fact]
+    public void ConstructorWithNullHttpClientThrows()
+    {
+        // Act
+        Action act = () => _ = new DefaultHttpRequestHandler((HttpClient)null!);
+
+        // Assert
+        act.Should().Throw<ArgumentNullException>();
+    }
+
+    [Fact]
+    public async Task ConstructorWithHttpClientUsesSuppliedClientForAllRequestsAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler messageHandler = new((req, _) =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent("ok", Encoding.UTF8, "text/plain"),
+            }));
+        using HttpClient suppliedClient = new(messageHandler);
+        await using DefaultHttpRequestHandler handler = new(suppliedClient);
+        HttpRequestInfo request = new() { Method = "GET", Url = TestUrl };
+
+        // Act
+        HttpRequestResult result = await handler.SendAsync(request);
+
+        // Assert - the supplied HttpClient's underlying handler saw the request
+        messageHandler.LastRequest.Should().NotBeNull();
+        messageHandler.LastRequest!.RequestUri!.ToString().Should().Be(TestUrl);
+        result.Body.Should().Be("ok");
+    }
+
+    [Fact]
+    public async Task DisposeAsyncDoesNotDisposeCallerSuppliedHttpClientAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler messageHandler = new((req, _) =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)));
+        using HttpClient suppliedClient = new(messageHandler);
+
+        // Act
+        DefaultHttpRequestHandler handler = new(suppliedClient);
+        await handler.DisposeAsync();
+
+        // Assert - supplied client remains usable (not disposed)
+        Func<Task> act = async () => await suppliedClient.GetAsync(new Uri(TestUrl));
+        await act.Should().NotThrowAsync<ObjectDisposedException>();
+    }
+
+    #endregion
+
+    #region Argument Validation Tests
+
+    [Fact]
+    public async Task SendAsyncWithNullRequestThrowsAsync()
+    {
+        // Arrange
+        await using DefaultHttpRequestHandler handler = new();
+
+        // Act
+        Func<Task> act = async () => await handler.SendAsync(null!);
+
+        // Assert
+        await act.Should().ThrowAsync<ArgumentNullException>();
+    }
+
+    [Fact]
+    public async Task SendAsyncWithEmptyUrlThrowsAsync()
+    {
+        // Arrange
+        await using DefaultHttpRequestHandler handler = new();
+        HttpRequestInfo request = new() { Method = "GET", Url = "" };
+
+        // Act
+        Func<Task> act = async () => await handler.SendAsync(request);
+
+        // Assert
+        await act.Should().ThrowAsync<ArgumentException>();
+    }
+
+    [Fact]
+    public async Task SendAsyncWithEmptyMethodThrowsAsync()
+    {
+        // Arrange
+        await using DefaultHttpRequestHandler handler = new();
+        HttpRequestInfo request = new() { Method = "", Url = TestUrl };
+
+        // Act
+        Func<Task> act = async () => await handler.SendAsync(request);
+
+        // Assert
+        await act.Should().ThrowAsync<ArgumentException>();
+    }
+
+    #endregion
+
+    #region Send Behavior Tests
+
+    [Fact]
+    public async Task SendAsyncUsesProvidedHttpClientAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler messageHandler = new((req, _) =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)
+            {
+                Content = new StringContent("hello", Encoding.UTF8, "text/plain"),
+            }));
+
+        await using DefaultHttpRequestHandler handler = new((_, _) => Task.FromResult<HttpClient?>(new HttpClient(messageHandler)));
+
+        HttpRequestInfo request = new() { Method = "GET", Url = TestUrl };
+
+        // Act
+        HttpRequestResult result = await handler.SendAsync(request);
+
+        // Assert
+        messageHandler.LastRequest.Should().NotBeNull();
+        messageHandler.LastRequest!.Method.Should().Be(HttpMethod.Get);
+        messageHandler.LastRequest.RequestUri!.ToString().Should().Be(TestUrl);
+        result.StatusCode.Should().Be(200);
+        result.IsSuccessStatusCode.Should().BeTrue();
+        result.Body.Should().Be("hello");
+    }
+
+    [Fact]
+    public async Task SendAsyncMapsAllKnownMethodsAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler messageHandler = new((req, _) =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)));
+
+        await using DefaultHttpRequestHandler handler = new((_, _) => Task.FromResult<HttpClient?>(new HttpClient(messageHandler)));
+
+        foreach (string method in new[] { "GET", "POST", "PUT", "PATCH", "DELETE", "CUSTOM" })
+        {
+            HttpRequestInfo request = new() { Method = method, Url = TestUrl };
+
+            // Act
+            await handler.SendAsync(request);
+
+            // Assert
+            messageHandler.LastRequest!.Method.Method.Should().Be(method);
+        }
+    }
+
+    [Fact]
+    public async Task SendAsyncNormalizesWhitespaceAroundCustomMethodAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler messageHandler = new((req, _) =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)));
+        await using DefaultHttpRequestHandler handler = new((_, _) => Task.FromResult<HttpClient?>(new HttpClient(messageHandler)));
+        HttpRequestInfo request = new() { Method = "  custom  ", Url = TestUrl };
+
+        // Act
+        await handler.SendAsync(request);
+
+        // Assert - fallback path should apply the same Trim/ToUpperInvariant normalization.
+        messageHandler.LastRequest!.Method.Method.Should().Be("CUSTOM");
+    }
+
+    [Fact]
+    public async Task SendAsyncAppliesBodyAndContentTypeAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler messageHandler = new((req, _) =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)));
+
+        await using DefaultHttpRequestHandler handler = new((_, _) => Task.FromResult<HttpClient?>(new HttpClient(messageHandler)));
+
+        HttpRequestInfo request = new()
+        {
+            Method = "POST",
+            Url = TestUrl,
+            Body = "{\"hello\":\"world\"}",
+            BodyContentType = "application/json",
+        };
+
+        // Act
+        await handler.SendAsync(request);
+
+        // Assert
+        messageHandler.LastRequestBody.Should().Be("{\"hello\":\"world\"}");
+        messageHandler.LastRequestContentType.Should().Be("application/json");
+    }
+
+    [Fact]
+    public async Task SendAsyncAppliesRequestHeadersAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler messageHandler = new((req, _) =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)));
+
+        await using DefaultHttpRequestHandler handler = new((_, _) => Task.FromResult<HttpClient?>(new HttpClient(messageHandler)));
+
+        HttpRequestInfo request = new()
+        {
+            Method = "GET",
+            Url = TestUrl,
+            Headers = new Dictionary<string, string>
+            {
+                ["Authorization"] = "Bearer secret",
+                ["Accept"] = "application/json",
+            },
+        };
+
+        // Act
+        await handler.SendAsync(request);
+
+        // Assert
+        messageHandler.LastRequest!.Headers.Authorization!.ToString().Should().Be("Bearer secret");
+        messageHandler.LastRequest.Headers.Accept.Should().Contain(mediaType => mediaType.MediaType == "application/json");
+    }
+
+    [Fact]
+    public async Task SendAsyncRoutesContentHeadersToBodyAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler messageHandler = new((req, _) =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)));
+
+        await using DefaultHttpRequestHandler handler = new((_, _) => Task.FromResult<HttpClient?>(new HttpClient(messageHandler)));
+
+        HttpRequestInfo request = new()
+        {
+            Method = "POST",
+            Url = TestUrl,
+            Body = "raw",
+            BodyContentType = "text/plain",
+            Headers = new Dictionary<string, string>
+            {
+                ["Content-Language"] = "en-US",
+            },
+        };
+
+        // Act
+        await handler.SendAsync(request);
+
+        // Assert
+        messageHandler.LastRequest!.Content!.Headers.ContentLanguage.Should().Contain("en-US");
+    }
+
+    [Fact]
+    public async Task SendAsyncCapturesResponseHeadersAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler messageHandler = new((req, _) =>
+        {
+#pragma warning disable CA2025
+            HttpResponseMessage response = new(HttpStatusCode.OK)
+            {
+                Content = new StringContent("ok", Encoding.UTF8, "text/plain"),
+            };
+            response.Headers.Add("X-Request-Id", "request-1");
+            response.Headers.Add("Set-Cookie", s_setCookieValues);
+            return Task.FromResult(response);
+#pragma warning restore CA2025
+        });
+
+        await using DefaultHttpRequestHandler handler = new((_, _) => Task.FromResult<HttpClient?>(new HttpClient(messageHandler)));
+
+        HttpRequestInfo request = new() { Method = "GET", Url = TestUrl };
+
+        // Act
+        HttpRequestResult result = await handler.SendAsync(request);
+
+        // Assert
+        result.Headers.Should().NotBeNull();
+        result.Headers!.Should().ContainKey("X-Request-Id");
+        result.Headers!["Set-Cookie"].Should().BeEquivalentTo(s_setCookieValues);
+        // Content headers also flattened in.
+        result.Headers!.Should().ContainKey("Content-Type");
+    }
+
+    [Fact]
+    public async Task SendAsyncReturnsFailureStatusWithoutThrowingAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler messageHandler = new((req, _) =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.BadRequest)
+            {
+                Content = new StringContent("bad request", Encoding.UTF8, "text/plain"),
+            }));
+
+        await using DefaultHttpRequestHandler handler = new((_, _) => Task.FromResult<HttpClient?>(new HttpClient(messageHandler)));
+
+        HttpRequestInfo request = new() { Method = "GET", Url = TestUrl };
+
+        // Act
+        HttpRequestResult result = await handler.SendAsync(request);
+
+        // Assert
+        result.IsSuccessStatusCode.Should().BeFalse();
+        result.StatusCode.Should().Be(400);
+        result.Body.Should().Be("bad request");
+    }
+
+    [Fact]
+    public async Task SendAsyncTimeoutCancelsRequestAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler messageHandler = new(async (req, ct) =>
+        {
+            await Task.Delay(TimeSpan.FromSeconds(5), ct).ConfigureAwait(false);
+            return new HttpResponseMessage(HttpStatusCode.OK);
+        });
+
+        await using DefaultHttpRequestHandler handler = new((_, _) => Task.FromResult<HttpClient?>(new HttpClient(messageHandler)));
+
+        HttpRequestInfo request = new()
+        {
+            Method = "GET",
+            Url = TestUrl,
+            Timeout = TimeSpan.FromMilliseconds(50),
+        };
+
+        // Act
+        Func<Task> act = async () => await handler.SendAsync(request);
+
+        // Assert
+        await act.Should().ThrowAsync<OperationCanceledException>();
+    }
+
+    [Fact]
+    public async Task SendAsyncFallsBackToOwnedClientWhenProviderReturnsNullAsync()
+    {
+        // Arrange
+        int providerCallCount = 0;
+        await using DefaultHttpRequestHandler handler = new((_, _) =>
+        {
+            providerCallCount++;
+            return Task.FromResult<HttpClient?>(null);
+        });
+
+        HttpRequestInfo request = new() { Method = "GET", Url = "http://127.0.0.1:1/" };
+
+        // Act - owned client will attempt real network and fail, but provider path should have been consulted first.
+        Func<Task> act = async () => await handler.SendAsync(request);
+
+        // Assert
+        await act.Should().ThrowAsync<Exception>();
+        providerCallCount.Should().Be(1);
+    }
+
+    #endregion
+
+    #region DisposeAsync
+
+    [Fact]
+    public async Task DisposeAsyncCompletesAsync()
+    {
+        // Arrange
+        DefaultHttpRequestHandler handler = new();
+
+        // Act
+        Func<Task> act = async () => await handler.DisposeAsync();
+
+        // Assert
+        await act.Should().NotThrowAsync();
+    }
+
+    [Fact]
+    public async Task DisposeAsyncCalledMultipleTimesSucceedsAsync()
+    {
+        // Arrange
+        DefaultHttpRequestHandler handler = new();
+
+        // Act
+        await handler.DisposeAsync();
+        Func<Task> second = async () => await handler.DisposeAsync();
+
+        // Assert
+        await second.Should().NotThrowAsync();
+    }
+
+    #endregion
+
+    #region Query Parameters and Connection Tests
+
+    [Fact]
+    public async Task QueryParametersAreAppendedToUrlAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler fake = new(static (req, _) =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(string.Empty) }));
+        await using DefaultHttpRequestHandler handler = new((_, _) => Task.FromResult<HttpClient?>(new HttpClient(fake)));
+
+        HttpRequestInfo info = new()
+        {
+            Method = "GET",
+            Url = TestUrl,
+            QueryParameters = new Dictionary<string, string>
+            {
+                ["filter"] = "active items",
+                ["ids"] = "1,2,3",
+            },
+        };
+
+        // Act
+        await handler.SendAsync(info);
+
+        // Assert
+        fake.LastRequest.Should().NotBeNull();
+        string? query = fake.LastRequest!.RequestUri!.Query;
+        query.Should().Contain("filter=active%20items");
+        query.Should().Contain("ids=1%2C2%2C3");
+    }
+
+    [Fact]
+    public async Task QueryParametersPreserveExistingQueryStringAsync()
+    {
+        // Arrange
+        TestHttpMessageHandler fake = new(static (req, _) =>
+            Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK) { Content = new StringContent(string.Empty) }));
+        await using DefaultHttpRequestHandler handler = new((_, _) => Task.FromResult<HttpClient?>(new HttpClient(fake)));
+
+        HttpRequestInfo info = new()
+        {
+            Method = "GET",
+            Url = TestUrl + "?existing=yes",
+            QueryParameters = new Dictionary<string, string>
+            {
+                ["added"] = "true",
+            },
+        };
+
+        // Act
+        await handler.SendAsync(info);
+
+        // Assert
+        fake.LastRequest!.RequestUri!.Query.Should().Be("?existing=yes&added=true");
+    }
+
+    #endregion
+
+    private sealed class TestHttpMessageHandler : HttpMessageHandler
+    {
+        private readonly Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>> _responseFactory;
+
+        public TestHttpMessageHandler(Func<HttpRequestMessage, CancellationToken, Task<HttpResponseMessage>> responseFactory)
+        {
+            this._responseFactory = responseFactory;
+        }
+
+        public HttpRequestMessage? LastRequest { get; private set; }
+
+        public string? LastRequestBody { get; private set; }
+
+        public string? LastRequestContentType { get; private set; }
+
+        protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
+        {
+            this.LastRequest = request;
+            if (request.Content is not null)
+            {
+#if NET
+                this.LastRequestBody = await request.Content.ReadAsStringAsync(cancellationToken).ConfigureAwait(false);
+#else
+                this.LastRequestBody = await request.Content.ReadAsStringAsync().ConfigureAwait(false);
+#endif
+                this.LastRequestContentType = request.Content.Headers.ContentType?.MediaType;
+            }
+            return await this._responseFactory(request, cancellationToken).ConfigureAwait(false);
+        }
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Extensions/ChatMessageExtensionsTests.cs

@@ -769,4 +769,165 @@ public sealed class ChatMessageExtensionsTests
                 break;
         }
     }
+
+    [Fact]
+    public void MergeForLastMessageReturnsInputWhenInputMessageIsNull()
+    {
+        // Arrange
+        ChatMessage input = new(ChatRole.User, "hello") { MessageId = "local" };
+
+        // Act
+        ChatMessage result = input.MergeForLastMessage(null);
+
+        // Assert
+        Assert.Same(input, result);
+    }
+
+    [Fact]
+    public void MergeForLastMessageReturnsSameInstanceAsRoundTripped()
+    {
+        // Arrange: returning the round-tripped instance keeps the merge forward-compatible
+        // with future ChatMessage properties (e.g., new metadata fields) without explicit copies.
+        ChatMessage input = new(ChatRole.User, "original");
+        ChatMessage roundTripped = new(ChatRole.User, "stripped") { MessageId = "server" };
+
+        // Act
+        ChatMessage result = input.MergeForLastMessage(roundTripped);
+
+        // Assert
+        Assert.Same(roundTripped, result);
+    }
+
+    [Fact]
+    public void MergeForLastMessagePrefersOriginalTextOverRoundTrippedText()
+    {
+        // Arrange
+        ChatMessage input = new(ChatRole.User, "original text");
+        ChatMessage roundTripped = new(ChatRole.User, "stripped") { MessageId = "server-id" };
+
+        // Act
+        ChatMessage result = input.MergeForLastMessage(roundTripped);
+
+        // Assert
+        Assert.Equal("server-id", result.MessageId);
+        Assert.Equal("original text", result.Text);
+        TextContent text = Assert.IsType<TextContent>(Assert.Single(result.Contents));
+        Assert.Equal("original text", text.Text);
+    }
+
+    [Fact]
+    public void MergeForLastMessageReplacesTextInPlaceAndKeepsServerMedia()
+    {
+        // Arrange
+        HostedFileContent serverRef = new("file-abc");
+        ChatMessage input = new(ChatRole.User, [new TextContent("look at this:"), new DataContent("data:image/jpeg;base64,QUJD", "image/jpeg")]);
+        ChatMessage roundTripped = new(ChatRole.User, [new TextContent("stripped"), serverRef]) { MessageId = "server-id" };
+
+        // Act
+        ChatMessage result = input.MergeForLastMessage(roundTripped);
+
+        // Assert: server's text slot is replaced with original text; server's media reference is preserved.
+        Assert.Equal("server-id", result.MessageId);
+        Assert.Collection(result.Contents,
+            c => Assert.Equal("look at this:", Assert.IsType<TextContent>(c).Text),
+            c => Assert.Same(serverRef, c));
+    }
+
+    [Fact]
+    public void MergeForLastMessageAppendsOriginalTextWhenRoundTripHasNoTextSlot()
+    {
+        // Arrange: round-tripped message has only media (no text slot to replace).
+        HostedFileContent serverRef = new("file-1");
+        ChatMessage input = new(ChatRole.User, [new TextContent("middle"), new DataContent("data:image/jpeg;base64,QUE=", "image/jpeg")]);
+        ChatMessage roundTripped = new(ChatRole.User, [serverRef]) { MessageId = "id" };
+
+        // Act
+        ChatMessage result = input.MergeForLastMessage(roundTripped);
+
+        // Assert: media kept; original text appended at end.
+        Assert.Collection(result.Contents,
+            c => Assert.Same(serverRef, c),
+            c => Assert.Equal("middle", Assert.IsType<TextContent>(c).Text));
+    }
+
+    [Fact]
+    public void MergeForLastMessageReplacesMultipleTextSlotsInOrder()
+    {
+        // Arrange: input has two text items; round-tripped has two text slots interleaved with media.
+        HostedFileContent firstRef = new("file-1");
+        HostedFileContent secondRef = new("file-2");
+        ChatMessage input = new(ChatRole.User, [new TextContent("first"), new TextContent("second")]);
+        ChatMessage roundTripped = new(ChatRole.User, [firstRef, new TextContent("a"), secondRef, new TextContent("b")]) { MessageId = "id" };
+
+        // Act
+        ChatMessage result = input.MergeForLastMessage(roundTripped);
+
+        // Assert
+        Assert.Collection(result.Contents,
+            c => Assert.Same(firstRef, c),
+            c => Assert.Equal("first", Assert.IsType<TextContent>(c).Text),
+            c => Assert.Same(secondRef, c),
+            c => Assert.Equal("second", Assert.IsType<TextContent>(c).Text));
+    }
+
+    [Fact]
+    public void MergeForLastMessageFallsBackToInputTextWhenInputHasNoTextContent()
+    {
+        // Arrange: ChatMessage(role, "string") populates Text but no explicit TextContent
+        // when Contents is initially empty in some construction paths. Verify we still
+        // recover the original Text via input.Text.
+        ChatMessage input = new(ChatRole.User, "fallback text");
+        ChatMessage roundTripped = new(ChatRole.User, [new TextContent("stripped")]) { MessageId = "id" };
+
+        // Act
+        ChatMessage result = input.MergeForLastMessage(roundTripped);
+
+        // Assert
+        Assert.Equal("fallback text", Assert.IsType<TextContent>(Assert.Single(result.Contents)).Text);
+    }
+
+    [Fact]
+    public void MergeForLastMessagePreservesServerAuthoredProperties()
+    {
+        // Arrange: server (round-trip) is authoritative for metadata. Returning the
+        // round-tripped instance means any future ChatMessage property is automatically
+        // preserved without code changes here.
+        ChatMessage input = new(ChatRole.User, "hi")
+        {
+            AuthorName = "client-side",
+            AdditionalProperties = new AdditionalPropertiesDictionary { ["client"] = "value" },
+        };
+        ChatMessage roundTripped = new(ChatRole.User, [new TextContent("stripped")])
+        {
+            MessageId = "server",
+            AuthorName = "server-side",
+            AdditionalProperties = new AdditionalPropertiesDictionary { ["server"] = "value" },
+        };
+
+        // Act
+        ChatMessage result = input.MergeForLastMessage(roundTripped);
+
+        // Assert
+        Assert.Equal("server", result.MessageId);
+        Assert.Equal("server-side", result.AuthorName);
+        Assert.NotNull(result.AdditionalProperties);
+        Assert.True(result.AdditionalProperties.ContainsKey("server"));
+        Assert.False(result.AdditionalProperties.ContainsKey("client"));
+    }
+
+    [Fact]
+    public void MergeForLastMessageHandlesEmptyInputContents()
+    {
+        // Arrange
+        ChatMessage input = new(ChatRole.User, new List<AIContent>());
+        HostedFileContent serverRef = new("file-only");
+        ChatMessage roundTripped = new(ChatRole.User, [serverRef]) { MessageId = "id" };
+
+        // Act
+        ChatMessage result = input.MergeForLastMessage(roundTripped);
+
+        // Assert: nothing to splice; round-tripped returned unchanged.
+        Assert.Same(roundTripped, result);
+        Assert.Equal("file-only", Assert.IsType<HostedFileContent>(Assert.Single(result.Contents)).FileId);
+    }
 }

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

@@ -0,0 +1,759 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Agents.AI.Workflows.Declarative.ObjectModel;
+using Microsoft.Agents.AI.Workflows.Declarative.PowerFx;
+using Microsoft.Agents.ObjectModel;
+using Microsoft.Extensions.AI;
+using Microsoft.PowerFx.Types;
+using Moq;
+
+namespace Microsoft.Agents.AI.Workflows.Declarative.UnitTests.ObjectModel;
+
+/// <summary>
+/// Tests for <see cref="HttpRequestExecutor"/>.
+/// </summary>
+public sealed class HttpRequestExecutorTest(ITestOutputHelper output) : WorkflowActionExecutorTest(output)
+{
+    private const string TestUrl = "https://api.example.com/data";
+
+    private readonly Mock<ResponseAgentProvider> _agentProvider = new(MockBehavior.Loose);
+
+    [Fact]
+    public void InvalidModel()
+    {
+        // Arrange
+        Mock<IHttpRequestHandler> mockHandler = new();
+
+        // Act & Assert
+        Assert.Throws<DeclarativeModelException>(() => new HttpRequestExecutor(
+            new HttpRequestAction(),
+            mockHandler.Object,
+            this._agentProvider.Object,
+            this.State));
+    }
+
+    [Fact]
+    public void HttpRequestIsDiscreteAction()
+    {
+        // Arrange
+        Mock<IHttpRequestHandler> mockHandler = new();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestIsDiscreteAction),
+            url: TestUrl,
+            method: HttpMethodType.Get);
+        HttpRequestExecutor action = new(model, mockHandler.Object, this._agentProvider.Object, this.State);
+
+        // Act & Assert — IsDiscreteAction should be true for HttpRequest (single-step action).
+        VerifyIsDiscrete(action, isDiscrete: true);
+    }
+
+    [Fact]
+    public async Task HttpGetReturnsJsonObjectAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        const string ResponseVar = "Result";
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpGetReturnsJsonObjectAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            responseVariable: ResponseVar);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("{\"key\":\"value\",\"number\":42}"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        Assert.IsType<RecordValue>(this.State.Get(ResponseVar), exactMatch: false);
+        handler.VerifySent(info => info.Method == "GET" && info.Url == TestUrl);
+    }
+
+    [Fact]
+    public async Task HttpGetReturnsPlainStringAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        const string ResponseVar = "Result";
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpGetReturnsPlainStringAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            responseVariable: ResponseVar);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("not-json content"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        this.VerifyState(ResponseVar, FormulaValue.New("not-json content"));
+    }
+
+    [Fact]
+    public async Task HttpGetWithEmptyBodyYieldsBlankAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        const string ResponseVar = "Result";
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpGetWithEmptyBodyYieldsBlankAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            responseVariable: ResponseVar);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult(null));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        this.VerifyUndefined(ResponseVar);
+    }
+
+    [Fact]
+    public async Task HttpGetForwardsHeadersAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpGetForwardsHeadersAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            headers: new Dictionary<string, string>
+            {
+                ["Authorization"] = "Bearer token",
+                ["Accept"] = "application/json",
+            });
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("{}"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        handler.VerifySent(info =>
+            info.Headers?["Authorization"] == "Bearer token" &&
+            info.Headers?["Accept"] == "application/json");
+    }
+
+    [Fact]
+    public async Task HttpPostWithJsonBodyAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpPostWithJsonBodyAsync),
+            url: TestUrl,
+            method: HttpMethodType.Post,
+            jsonBody: new StringDataValue("hello"));
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("{}"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        handler.VerifySent(info =>
+            info.Method == "POST" &&
+            info.BodyContentType == "application/json" &&
+            info.Body == "\"hello\"");
+    }
+
+    [Fact]
+    public async Task HttpPostWithRawBodyAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpPostWithRawBodyAsync),
+            url: TestUrl,
+            method: HttpMethodType.Post,
+            rawBody: "raw body content",
+            rawContentType: "text/plain");
+
+        MockHttpRequestHandler handler = new(HttpRequestResult(""));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        handler.VerifySent(info =>
+            info.BodyContentType == "text/plain" &&
+            info.Body == "raw body content");
+    }
+
+    [Fact]
+    public async Task HttpRequestRaisesOnErrorByDefaultAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestRaisesOnErrorByDefaultAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("server error", statusCode: 500, isSuccess: false));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act & Assert
+        await Assert.ThrowsAsync<DeclarativeActionException>(() => this.ExecuteAsync(action));
+    }
+
+    [Fact]
+    public async Task HttpRequestFailureExceptionTruncatesLongBodyAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestFailureExceptionTruncatesLongBodyAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get);
+
+        string longBody = new('x', 10_000);
+        MockHttpRequestHandler handler = new(HttpRequestResult(longBody, statusCode: 500, isSuccess: false));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        DeclarativeActionException exception =
+            await Assert.ThrowsAsync<DeclarativeActionException>(() => this.ExecuteAsync(action));
+
+        // Assert - message contains status and truncation marker, bounded in length, never the full body.
+        Assert.Contains("500", exception.Message);
+        Assert.Contains("[truncated]", exception.Message);
+        Assert.DoesNotContain(longBody, exception.Message);
+        Assert.True(exception.Message.Length < 512, $"Exception message too long: {exception.Message.Length} chars.");
+    }
+
+    [Fact]
+    public async Task HttpRequestFailureExceptionOmitsEmptyBodyAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestFailureExceptionOmitsEmptyBodyAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult(body: null, statusCode: 404, isSuccess: false));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        DeclarativeActionException exception =
+            await Assert.ThrowsAsync<DeclarativeActionException>(() => this.ExecuteAsync(action));
+
+        // Assert - status present, no stray "Body: ''" noise.
+        Assert.Contains("404", exception.Message);
+        Assert.DoesNotContain("Body:", exception.Message);
+    }
+
+    [Fact]
+    public async Task HttpRequestFailureExceptionSanitizesControlCharsAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestFailureExceptionSanitizesControlCharsAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("line1\r\nline2\tend", statusCode: 400, isSuccess: false));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        DeclarativeActionException exception =
+            await Assert.ThrowsAsync<DeclarativeActionException>(() => this.ExecuteAsync(action));
+
+        // Assert - CR/LF/TAB collapsed to spaces so the message stays on one line.
+        Assert.DoesNotContain("\r", exception.Message);
+        Assert.DoesNotContain("\n", exception.Message);
+        Assert.DoesNotContain("\t", exception.Message);
+        Assert.Contains("line1", exception.Message);
+        Assert.Contains("line2", exception.Message);
+    }
+
+    [Fact]
+    public async Task HttpRequestPassesTimeoutToHandlerAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestPassesTimeoutToHandlerAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            timeoutMilliseconds: 1500);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("{}"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        handler.VerifySent(info =>
+            info.Timeout is not null &&
+            info.Timeout.Value == TimeSpan.FromMilliseconds(1500));
+    }
+
+    [Fact]
+    public async Task HttpRequestTimeoutRaisesDeclarativeExceptionAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestTimeoutRaisesDeclarativeExceptionAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get);
+
+        MockHttpRequestHandler handler = new(
+            HttpRequestResult("{}"),
+            throwOnSend: new OperationCanceledException());
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act & Assert
+        await Assert.ThrowsAsync<DeclarativeActionException>(() => this.ExecuteAsync(action));
+    }
+
+    [Fact]
+    public async Task HttpRequestTransportFailureRaisesDeclarativeExceptionAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestTransportFailureRaisesDeclarativeExceptionAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get);
+
+        MockHttpRequestHandler handler = new(
+            HttpRequestResult("{}"),
+            throwOnSend: new InvalidOperationException("transport failure"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act & Assert
+        await Assert.ThrowsAsync<DeclarativeActionException>(() => this.ExecuteAsync(action));
+    }
+
+    [Fact]
+    public async Task HttpRequestStoresResponseHeadersAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        const string HeaderVar = "Headers";
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestStoresResponseHeadersAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            responseHeadersVariable: HeaderVar);
+
+        Dictionary<string, IReadOnlyList<string>> responseHeaders = new(StringComparer.OrdinalIgnoreCase)
+        {
+            ["X-Request-Id"] = ["abc-123"],
+            ["Set-Cookie"] = ["a=1", "b=2"],
+        };
+        MockHttpRequestHandler handler = new(HttpRequestResult("{}", headers: responseHeaders));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        FormulaValue storedHeaders = this.State.Get(HeaderVar);
+        Assert.IsType<RecordValue>(storedHeaders, exactMatch: false);
+    }
+
+    [Fact]
+    public async Task HttpRequestForwardsQueryParametersAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestForwardsQueryParametersAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            queryParameters: new Dictionary<string, DataValue>
+            {
+                ["filter"] = StringDataValue.Create("active"),
+                ["limit"] = NumberDataValue.Create(10),
+                ["includeDeleted"] = BooleanDataValue.Create(false),
+            });
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("{}"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        handler.VerifySent(info =>
+            info.QueryParameters?.Count == 3 &&
+            info.QueryParameters["filter"] == "active" &&
+            info.QueryParameters["limit"] == "10" &&
+            info.QueryParameters["includeDeleted"] == "false");
+    }
+
+    [Fact]
+    public async Task HttpRequestAddsResponseToConversationAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        const string ConversationId = "conv-12345";
+        const string ResponseBody = "response-text";
+
+        this._agentProvider
+            .Setup(p => p.CreateMessageAsync(It.IsAny<string>(), It.IsAny<ChatMessage>(), It.IsAny<CancellationToken>()))
+            .Returns<string, ChatMessage, CancellationToken>((_, message, _) => Task.FromResult(message));
+
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestAddsResponseToConversationAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            conversationId: ConversationId);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult(ResponseBody));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        this._agentProvider.Verify(
+            p => p.CreateMessageAsync(
+                ConversationId,
+                It.Is<ChatMessage>(m => m.Role == ChatRole.Assistant && m.Text == ResponseBody),
+                It.IsAny<CancellationToken>()),
+            Times.Once);
+    }
+
+    [Fact]
+    public async Task HttpRequestWithoutConversationIdSkipsConversationAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestWithoutConversationIdSkipsConversationAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("response"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        this._agentProvider.Verify(
+            p => p.CreateMessageAsync(It.IsAny<string>(), It.IsAny<ChatMessage>(), It.IsAny<CancellationToken>()),
+            Times.Never);
+    }
+
+    [Fact]
+    public async Task HttpRequestForwardsConnectionNameAsync()
+    {
+        // Arrange
+        this.State.InitializeSystem();
+        const string ConnectionName = "my-connection";
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestForwardsConnectionNameAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            connectionName: ConnectionName);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("{}"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        handler.VerifySent(info => info.ConnectionName == ConnectionName);
+    }
+
+    [Fact]
+    public async Task HttpRequestEmptyConversationIdSkipsConversationAsync()
+    {
+        // Arrange - empty-string conversationId should be treated as unset.
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestEmptyConversationIdSkipsConversationAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            conversationId: "");
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("response"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        this._agentProvider.Verify(
+            p => p.CreateMessageAsync(It.IsAny<string>(), It.IsAny<ChatMessage>(), It.IsAny<CancellationToken>()),
+            Times.Never);
+    }
+
+    [Fact]
+    public async Task HttpRequestEmptyResponseBodySkipsConversationAsync()
+    {
+        // Arrange - conversationId set, but empty body should not produce a conversation message.
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestEmptyResponseBodySkipsConversationAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            conversationId: "conv-1");
+
+        MockHttpRequestHandler handler = new(HttpRequestResult(""));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        this._agentProvider.Verify(
+            p => p.CreateMessageAsync(It.IsAny<string>(), It.IsAny<ChatMessage>(), It.IsAny<CancellationToken>()),
+            Times.Never);
+    }
+
+    [Fact]
+    public async Task HttpGetReturnsJsonArrayAsync()
+    {
+        // Arrange - exercises JsonValueKind.Array branch of ParseResponseBody.
+        this.State.InitializeSystem();
+        const string ResponseVar = "Result";
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpGetReturnsJsonArrayAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            responseVariable: ResponseVar);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("[1, 2, 3]"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        FormulaValue stored = this.State.Get(ResponseVar);
+        Assert.IsType<TableValue>(stored, exactMatch: false);
+    }
+
+    [Fact]
+    public async Task HttpGetWithEmptyHeaderValueDropsHeaderAsync()
+    {
+        // Arrange - empty header values should be filtered out (matches GetHeaders guard).
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpGetWithEmptyHeaderValueDropsHeaderAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            headers: new Dictionary<string, string>
+            {
+                ["X-Trace"] = "trace-1",
+                ["X-Empty"] = "",
+            });
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("{}"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        handler.VerifySent(info =>
+            info.Headers?.ContainsKey("X-Trace") == true &&
+            info.Headers?.ContainsKey("X-Empty") == false);
+    }
+
+    [Fact]
+    public async Task HttpRequestZeroTimeoutNotForwardedAsync()
+    {
+        // Arrange - non-positive timeouts should not be forwarded (handler default applies).
+        this.State.InitializeSystem();
+        HttpRequestAction model = this.CreateModel(
+            displayName: nameof(HttpRequestZeroTimeoutNotForwardedAsync),
+            url: TestUrl,
+            method: HttpMethodType.Get,
+            timeoutMilliseconds: 0);
+
+        MockHttpRequestHandler handler = new(HttpRequestResult("{}"));
+        HttpRequestExecutor action = new(model, handler.Object, this._agentProvider.Object, this.State);
+
+        // Act
+        await this.ExecuteAsync(action);
+
+        // Assert
+        VerifyModel(model, action);
+        handler.VerifySent(info => info.Timeout is null);
+    }
+
+    private static HttpRequestResult HttpRequestResult(
+        string? body,
+        int statusCode = 200,
+        bool isSuccess = true,
+        IReadOnlyDictionary<string, IReadOnlyList<string>>? headers = null) =>
+        new()
+        {
+            StatusCode = statusCode,
+            IsSuccessStatusCode = isSuccess,
+            Body = body,
+            Headers = headers,
+        };
+
+    private HttpRequestAction CreateModel(
+        string displayName,
+        string url,
+        HttpMethodType method,
+        string? responseVariable = null,
+        string? responseHeadersVariable = null,
+        IReadOnlyDictionary<string, string>? headers = null,
+        IReadOnlyDictionary<string, DataValue>? queryParameters = null,
+        string? conversationId = null,
+        string? connectionName = null,
+        DataValue? jsonBody = null,
+        string? rawBody = null,
+        string? rawContentType = null,
+        long? timeoutMilliseconds = null,
+        string? continueOnErrorStatusVariable = null,
+        string? continueOnErrorBodyVariable = null)
+    {
+        HttpRequestAction.Builder builder = new()
+        {
+            Id = this.CreateActionId(),
+            DisplayName = this.FormatDisplayName(displayName),
+            Url = new StringExpression.Builder(StringExpression.Literal(url)),
+            Method = new EnumExpression<HttpMethodTypeWrapper>.Builder(
+                EnumExpression<HttpMethodTypeWrapper>.Literal(HttpMethodTypeWrapper.Get(method))),
+        };
+
+        if (responseVariable is not null)
+        {
+            builder.Response = PropertyPath.Create(FormatVariablePath(responseVariable));
+        }
+
+        if (responseHeadersVariable is not null)
+        {
+            builder.ResponseHeaders = PropertyPath.Create(FormatVariablePath(responseHeadersVariable));
+        }
+
+        if (headers is not null)
+        {
+            foreach (KeyValuePair<string, string> header in headers)
+            {
+                builder.Headers.Add(header.Key, new StringExpression.Builder(StringExpression.Literal(header.Value)));
+            }
+        }
+
+        if (queryParameters is not null)
+        {
+            foreach (KeyValuePair<string, DataValue> parameter in queryParameters)
+            {
+                builder.QueryParameters.Add(parameter.Key, new ValueExpression.Builder(ValueExpression.Literal(parameter.Value)));
+            }
+        }
+
+        if (conversationId is not null)
+        {
+            builder.ConversationId = new StringExpression.Builder(StringExpression.Literal(conversationId));
+        }
+
+        if (connectionName is not null)
+        {
+            builder.Connection = new RemoteConnection.Builder
+            {
+                Name = new StringExpression.Builder(StringExpression.Literal(connectionName)),
+            };
+        }
+
+        if (jsonBody is not null)
+        {
+            builder.Body = new JsonRequestContent.Builder()
+            {
+                Content = new ValueExpression.Builder(ValueExpression.Literal(jsonBody)),
+            };
+        }
+        else if (rawBody is not null)
+        {
+            RawRequestContent.Builder rawBuilder = new()
+            {
+                Content = new StringExpression.Builder(StringExpression.Literal(rawBody)),
+            };
+            if (rawContentType is not null)
+            {
+                rawBuilder.ContentType = new StringExpression.Builder(StringExpression.Literal(rawContentType));
+            }
+            builder.Body = rawBuilder;
+        }
+
+        if (timeoutMilliseconds is not null)
+        {
+            builder.RequestTimeoutInMilliseconds = new IntExpression.Builder(IntExpression.Literal(timeoutMilliseconds.Value));
+        }
+
+        if (continueOnErrorStatusVariable is not null || continueOnErrorBodyVariable is not null)
+        {
+            ContinueOnErrorBehavior.Builder continueBuilder = new();
+            if (continueOnErrorStatusVariable is not null)
+            {
+                continueBuilder.StatusCode = PropertyPath.Create(FormatVariablePath(continueOnErrorStatusVariable));
+            }
+            if (continueOnErrorBodyVariable is not null)
+            {
+                continueBuilder.ErrorResponseBody = PropertyPath.Create(FormatVariablePath(continueOnErrorBodyVariable));
+            }
+            builder.ErrorHandling = continueBuilder;
+        }
+
+        return AssignParent<HttpRequestAction>(builder);
+    }
+
+    private sealed class MockHttpRequestHandler : Mock<IHttpRequestHandler>
+    {
+        private HttpRequestInfo? _lastRequest;
+
+        public MockHttpRequestHandler(HttpRequestResult result, Exception? throwOnSend = null)
+        {
+            this.Setup(handler => handler.SendAsync(It.IsAny<HttpRequestInfo>(), It.IsAny<CancellationToken>()))
+                .Returns<HttpRequestInfo, CancellationToken>((info, _) =>
+                {
+                    this._lastRequest = info;
+                    if (throwOnSend is not null)
+                    {
+                        throw throwOnSend;
+                    }
+                    return Task.FromResult(result);
+                });
+        }
+
+        public void VerifySent(Func<HttpRequestInfo, bool> predicate)
+        {
+            Assert.NotNull(this._lastRequest);
+            Assert.True(predicate(this._lastRequest!), "Sent HTTP request did not match expected predicate.");
+        }
+    }
+}

dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Workflows/HttpRequest.yaml

@@ -0,0 +1,15 @@
+kind: Workflow
+trigger:
+
+  kind: OnConversationStart
+  id: my_workflow
+  actions:
+
+    - kind: HttpRequestAction
+      id: http_request
+      method: GET
+      url: =Concatenate("https://api.example.test/items/", System.LastMessageText)
+      headers:
+        Accept: application/json
+      response: Local.HttpResult
+      responseHeaders: Local.HttpHeaders

python/AGENTS.md

@@ -69,6 +69,7 @@ python/
 
 ### Azure Integrations
 - [foundry](packages/foundry/README.md) - Microsoft Foundry chat, agent, memory, and embedding integrations
+- [azure-contentunderstanding](packages/azure-contentunderstanding/AGENTS.md) - Azure Content Understanding context provider
 - [azure-ai-search](packages/azure-ai-search/AGENTS.md) - Azure AI Search RAG
 - [azure-cosmos](packages/azure-cosmos/AGENTS.md) - Azure Cosmos DB-backed history provider
 - [azurefunctions](packages/azurefunctions/AGENTS.md) - Azure Functions hosting

python/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.2] - 2026-04-29
+
+### Added
+- **agent-framework-azure-contentunderstanding**: New alpha package — Azure AI Content Understanding context provider that auto-analyzes file attachments (documents, images, audio, video) and injects structured results into the LLM context, with multi-document session state, configurable timeout, output filtering via `AnalysisSection`, and auto-registered `list_documents` / `get_analyzed_document` tools ([#4829](https://github.com/microsoft/agent-framework/pull/4829))
+- **agent-framework-foundry-hosting**: Add hosted Durable Workflow support — propagate full conversation history to workflow agents and wire `Workflow.as_agent()` end-to-end via the foundry hosting layer ([#5531](https://github.com/microsoft/agent-framework/pull/5531))
+
+### Changed
+- **agent-framework-orchestrations**: [BREAKING] Standardize orchestration terminal outputs as `AgentResponse` so `Workflow.as_agent()` returns the final answer only; aligns sequential-approval (`with_request_info`) and concurrent (`intermediate_outputs=True`) flows on the same output contract ([#5301](https://github.com/microsoft/agent-framework/pull/5301))
+- **agent-framework-core**, **agent-framework-declarative**: Preserve `Workflow.run()` shared state across calls so multi-turn `WorkflowAgent` invocations retain context, accept `list[Message]` input in the declarative start executor, and coerce `Enum` values when serializing PowerFx symbols ([#5531](https://github.com/microsoft/agent-framework/pull/5531))
+- **dependencies**: Update workspace package dependencies and preserve `mcp[ws]` / `uvicorn[standard]` extras through override-dependencies in `/python` ([#5555](https://github.com/microsoft/agent-framework/pull/5555))
+
+### Fixed
+- **agent-framework-core**: Fix observability spans not being correctly nested when using streaming ([#5552](https://github.com/microsoft/agent-framework/pull/5552))
+- **agent-framework-openai**: Fix `file_search` citations breaking the assistant-message history roundtrip — skip `hosted_file` content in the assistant role so the Responses API no longer rejects `input_file` ([#5557](https://github.com/microsoft/agent-framework/pull/5557))
+
 ## [1.2.1] - 2026-04-28
 
 ### Added
@@ -1003,7 +1018,8 @@ Release candidate for **agent-framework-core** and **agent-framework-azure-ai**
 
 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.2.1...HEAD
+[Unreleased]: https://github.com/microsoft/agent-framework/compare/python-1.2.2...HEAD
+[1.2.2]: https://github.com/microsoft/agent-framework/compare/python-1.2.1...python-1.2.2
 [1.2.1]: https://github.com/microsoft/agent-framework/compare/python-1.2.0...python-1.2.1
 [1.2.0]: https://github.com/microsoft/agent-framework/compare/python-1.1.1...python-1.2.0
 [1.1.1]: https://github.com/microsoft/agent-framework/compare/python-1.1.0...python-1.1.1

python/PACKAGE_STATUS.md

@@ -18,6 +18,7 @@ Status is grouped into these buckets:
 | `agent-framework-a2a` | `python/packages/a2a` | `beta` |
 | `agent-framework-ag-ui` | `python/packages/ag-ui` | `beta` |
 | `agent-framework-anthropic` | `python/packages/anthropic` | `beta` |
+| `agent-framework-azure-contentunderstanding` | `python/packages/azure-contentunderstanding` | `alpha` |
 | `agent-framework-azure-ai-search` | `python/packages/azure-ai-search` | `beta` |
 | `agent-framework-azure-cosmos` | `python/packages/azure-cosmos` | `beta` |
 | `agent-framework-azurefunctions` | `python/packages/azurefunctions` | `beta` |

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.0b260428"
+version = "1.0.0b260429"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "a2a-sdk>=0.3.5,<0.3.24",
 ]
 

python/packages/ag-ui/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-framework-ag-ui"
-version = "1.0.0b260428"
+version = "1.0.0b260429"
 description = "AG-UI protocol integration for Agent Framework"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "ag-ui-protocol>=0.1.16,<0.2",
     "fastapi>=0.115.0,<0.133.1",
     "uvicorn[standard]>=0.30.0,<0.42.0"

python/packages/anthropic/agent_framework_anthropic/_chat_client.py

@@ -872,6 +872,8 @@ class RawAnthropicClient(
         tool_mode = validate_tool_mode(options.get("tool_choice"))
         if tool_mode is None:
             return result or None
+        if "allowed_tools" in tool_mode:
+            logger.warning("allowed_tools is not supported by Anthropic; the setting will be ignored")
         allow_multiple = options.get("allow_multiple_tool_calls")
         match tool_mode.get("mode"):
             case "auto":

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.0b260428"
+version = "1.0.0b260429"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "anthropic>=0.80.0,<0.80.1",
 ]
 

python/packages/azure-ai-search/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure AI Search integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260428"
+version = "1.0.0b260429"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "azure-search-documents>=11.7.0b2,<11.7.0b3",
 ]
 

python/packages/azure-contentunderstanding/.gitignore

@@ -0,0 +1,3 @@
+# Local-only files (not committed)
+_local_only/
+*_local_only*

python/packages/azure-contentunderstanding/AGENTS.md

@@ -0,0 +1,71 @@
+# AGENTS.md — azure-contentunderstanding
+
+## Package Overview
+
+`agent-framework-azure-contentunderstanding` integrates Azure Content Understanding (CU)
+into the Agent Framework as a context provider. It automatically analyzes file attachments
+(documents, images, audio, video) and injects structured results into the LLM context.
+
+## Public API
+
+| Symbol | Type | Description |
+|--------|------|-------------|
+| `ContentUnderstandingContextProvider` | class | Main context provider — extends `ContextProvider` |
+| `AnalysisSection` | enum | Output section selector (MARKDOWN, FIELDS, etc.) |
+| `DocumentStatus` | enum | Document lifecycle state (ANALYZING, UPLOADING, READY, FAILED) |
+| `FileSearchBackend` | ABC | Abstract vector store file operations interface |
+| `FileSearchConfig` | dataclass | Configuration for CU + vector store RAG mode |
+
+## Architecture
+
+- **`_context_provider.py`** — Main provider implementation. Overrides `before_run()` to detect
+  file attachments, call the CU API, manage session state with multi-document tracking,
+  and auto-register retrieval tools for follow-up turns.
+  - **Analyzer auto-detection** — When `analyzer_id=None` (default), `_resolve_analyzer_id()`
+    selects the CU analyzer based on media type prefix: `audio/` → `prebuilt-audioSearch`,
+    `video/` → `prebuilt-videoSearch`, everything else → `prebuilt-documentSearch`.
+  - **Multi-segment output** — CU splits long video/audio into multiple scene segments
+    (each a separate `contents[]` entry with its own `startTimeMs`, `endTimeMs`, `markdown`,
+    and `fields`). `_extract_sections()` produces:
+    - `segments`: list of per-segment dicts, each with `markdown`, `fields`, `start_time_s`, `end_time_s`
+    - `markdown`: concatenated at top level with `---` separators (for file_search uploads)
+    - `duration_seconds`: computed from global `min(startTimeMs)` → `max(endTimeMs)`
+    - Metadata (`kind`, `resolution`): taken from the first segment
+  - **Speaker diarization (not identification)** — CU transcripts label speakers as
+    `<Speaker 1>`, `<Speaker 2>`, etc. CU does **not** identify speakers by name.
+  - **file_search RAG** — When `FileSearchConfig` is provided, CU-extracted markdown is
+    uploaded to an OpenAI vector store and a `file_search` tool is registered on the context
+    instead of injecting the full document content. This enables token-efficient retrieval
+    for large documents.
+- **`_models.py`** — `AnalysisSection` enum, `DocumentStatus` enum, `DocumentEntry` TypedDict,
+  `FileSearchConfig` dataclass.
+- **`_file_search.py`** — `FileSearchBackend` ABC, `OpenAIFileSearchBackend`,
+  `FoundryFileSearchBackend`.
+
+## Key Patterns
+
+- Follows the Azure AI Search context provider pattern (same lifecycle, config style).
+- Uses provider-scoped `state` dict for multi-document tracking across turns.
+- Auto-registers `list_documents()` tool via `context.extend_tools()`.
+- Configurable timeout (`max_wait`) with `asyncio.create_task()` background fallback.
+- Strips supported binary attachments from `input_messages` to prevent LLM API errors.
+- Explicit `analyzer_id` always overrides auto-detection (user preference wins).
+- Vector store resources are cleaned up in `close()` / `__aexit__`.
+
+## Samples
+
+| Sample | Description |
+|--------|-------------|
+| `01_document_qa.py` | Upload a PDF via URL, ask questions about it |
+| `02_multi_turn_session.py` | AgentSession persistence across turns |
+| `03_multimodal_chat.py` | PDF + audio + video parallel analysis |
+| `04_invoice_processing.py` | Structured field extraction with `prebuilt-invoice` analyzer |
+| `05_large_doc_file_search.py` | CU extraction + OpenAI vector store RAG |
+| `02-devui/01-multimodal_agent/` | DevUI web UI for CU-powered chat |
+| `02-devui/02-file_search_agent/` | DevUI web UI combining CU + file_search RAG |
+
+## Running Tests
+
+```bash
+uv run poe test -P azure-contentunderstanding
+```

python/packages/azure-contentunderstanding/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/azure-contentunderstanding/README.md

@@ -0,0 +1,127 @@
+# Get Started with Azure Content Understanding in Microsoft Agent Framework
+
+Please install this package via pip:
+
+```bash
+pip install agent-framework-azure-contentunderstanding --pre
+```
+
+## Azure Content Understanding Integration
+
+### Prerequisites
+
+Before using this package, you need an Azure Content Understanding resource:
+
+1. An active **Azure subscription** ([create one for free](https://azure.microsoft.com/pricing/purchase-options/azure-account))
+2. A **Microsoft Foundry resource** created in a [supported region](https://learn.microsoft.com/azure/ai-services/content-understanding/language-region-support)
+3. **Default model deployments** configured for your resource (GPT-4.1, GPT-4.1-mini, text-embedding-3-large)
+
+Follow the [prerequisites section](https://learn.microsoft.com/azure/ai-services/content-understanding/quickstart/use-rest-api?tabs=portal%2Cdocument&pivots=programming-language-rest#prerequisites) in the Azure Content Understanding quickstart for setup instructions.
+
+### Introduction
+
+The Azure Content Understanding integration provides a context provider that automatically analyzes file attachments (documents, images, audio, video) using [Azure Content Understanding](https://learn.microsoft.com/azure/ai-services/content-understanding/) and injects structured results into the LLM context.
+
+- **Document & image analysis**: State-of-the-art OCR with markdown extraction, table preservation, and structured field extraction — handles scanned PDFs, handwritten content, and complex layouts
+- **Audio & video analysis**: Transcription, speaker diarization, and per-segment summaries
+- **Background processing**: Configurable timeout with async background fallback for large files
+- **file_search integration**: Optional vector store upload for token-efficient RAG on large documents
+
+> Learn more about Azure Content Understanding capabilities at [https://learn.microsoft.com/azure/ai-services/content-understanding/](https://learn.microsoft.com/azure/ai-services/content-understanding/)
+
+### Basic Usage Example
+
+See the [samples directory](samples/) which demonstrates:
+
+- Single PDF upload and Q&A ([01_document_qa](samples/01-get-started/01_document_qa.py))
+- Multi-turn sessions with cached results ([02_multi_turn_session](samples/01-get-started/02_multi_turn_session.py))
+- PDF + audio + video parallel analysis ([03_multimodal_chat](samples/01-get-started/03_multimodal_chat.py))
+- Structured field extraction with prebuilt-invoice ([04_invoice_processing](samples/01-get-started/04_invoice_processing.py))
+- CU extraction + OpenAI vector store RAG ([05_large_doc_file_search](samples/01-get-started/05_large_doc_file_search.py))
+- Interactive web UI with DevUI ([02-devui](samples/02-devui/))
+
+```python
+import asyncio
+from agent_framework import Agent, AgentSession, Message, Content
+from agent_framework.foundry import FoundryChatClient
+from agent_framework.foundry import ContentUnderstandingContextProvider
+from azure.identity import AzureCliCredential
+
+credential = AzureCliCredential()
+
+cu = ContentUnderstandingContextProvider(
+    endpoint="https://my-resource.cognitiveservices.azure.com/",
+    credential=credential,
+    max_wait=None,  # block until CU extraction completes before sending to LLM
+)
+
+client = FoundryChatClient(
+    project_endpoint="https://your-project.services.ai.azure.com",
+    model="gpt-4.1",
+    credential=credential,
+)
+
+async def main():
+    async with cu:
+        agent = Agent(
+            client=client,
+            name="DocumentQA",
+            instructions="You are a helpful document analyst.",
+            context_providers=[cu],
+        )
+        session = AgentSession()
+
+        response = await agent.run(
+            Message(role="user", contents=[
+                Content.from_text("What's on this invoice?"),
+                Content.from_uri(
+                    "https://raw.githubusercontent.com/Azure-Samples/"
+                    "azure-ai-content-understanding-assets/main/document/invoice.pdf",
+                    media_type="application/pdf",
+                    additional_properties={"filename": "invoice.pdf"},
+                ),
+            ]),
+            session=session,
+        )
+        print(response.text)
+
+asyncio.run(main())
+```
+
+### Supported File Types
+
+| Category | Types |
+|----------|-------|
+| Documents | PDF, DOCX, XLSX, PPTX, HTML, TXT, Markdown |
+| Images | JPEG, PNG, TIFF, BMP |
+| Audio | WAV, MP3, M4A, FLAC, OGG |
+| Video | MP4, MOV, AVI, WebM |
+
+For the complete list of supported file types and size limits, see [Azure Content Understanding service limits](https://learn.microsoft.com/azure/ai-services/content-understanding/service-limits#input-file-limits).
+
+### Environment Variables
+
+The provider supports automatic endpoint resolution from environment variables.
+When ``endpoint`` is not passed to the constructor, it is loaded from
+``AZURE_CONTENTUNDERSTANDING_ENDPOINT``:
+
+```python
+# Endpoint auto-loaded from AZURE_CONTENTUNDERSTANDING_ENDPOINT env var
+cu = ContentUnderstandingContextProvider(credential=credential)
+```
+
+Set these in your shell or in a `.env` file:
+
+```bash
+AZURE_CONTENTUNDERSTANDING_ENDPOINT=https://your-cu-resource.cognitiveservices.azure.com/
+AZURE_AI_PROJECT_ENDPOINT=https://your-project.services.ai.azure.com
+AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4.1
+```
+
+You also need to be logged in with `az login` (for `AzureCliCredential`).
+
+### Next steps
+
+- Explore the [samples directory](samples/) for complete code examples
+- Read the [Azure Content Understanding documentation](https://learn.microsoft.com/azure/ai-services/content-understanding/) for detailed service information
+- Learn more about the [Microsoft Agent Framework](https://aka.ms/agent-framework)

python/packages/azure-contentunderstanding/agent_framework_azure_contentunderstanding/__init__.py

@@ -0,0 +1,28 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Azure Content Understanding integration for Microsoft Agent Framework.
+
+Provides a context provider that analyzes file attachments (documents, images,
+audio, video) using Azure Content Understanding and injects structured results
+into the LLM context.
+"""
+
+import importlib.metadata
+
+from ._context_provider import ContentUnderstandingContextProvider
+from ._file_search import FileSearchBackend
+from ._models import AnalysisSection, DocumentStatus, FileSearchConfig
+
+try:
+    __version__ = importlib.metadata.version(__name__)
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AnalysisSection",
+    "ContentUnderstandingContextProvider",
+    "DocumentStatus",
+    "FileSearchBackend",
+    "FileSearchConfig",
+    "__version__",
+]

python/packages/azure-contentunderstanding/agent_framework_azure_contentunderstanding/_context_provider.py

@@ -0,0 +1,858 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Azure Content Understanding context provider using ContextProvider.
+
+This module provides ``ContentUnderstandingContextProvider``, built on the
+:class:`ContextProvider` hooks pattern.  It automatically detects file
+attachments, analyzes them via the Azure Content Understanding API, and
+injects structured results into the LLM context.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sys
+import time
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, ClassVar, TypedDict
+
+from agent_framework import (
+    AGENT_FRAMEWORK_USER_AGENT,
+    Content,
+    ContextProvider,
+    FunctionTool,
+    Message,
+    SessionContext,
+)
+from agent_framework._sessions import AgentSession
+from agent_framework._settings import load_settings
+from azure.ai.contentunderstanding.aio import ContentUnderstandingClient
+from azure.ai.contentunderstanding.models import AnalysisInput, AnalysisResult
+from azure.core.credentials import AzureKeyCredential
+from azure.core.credentials_async import AsyncTokenCredential
+
+if TYPE_CHECKING:
+    from agent_framework._agents import SupportsAgentRun
+
+from ._detection import (
+    detect_and_strip_files,
+)
+from ._extraction import extract_sections, format_result
+from ._models import AnalysisSection, DocumentEntry, DocumentStatus, FileSearchConfig
+
+if sys.version_info >= (3, 11):
+    from typing import Self  # pragma: no cover
+else:
+    from typing_extensions import Self  # pragma: no cover
+
+logger = logging.getLogger("agent_framework.azure_contentunderstanding")
+
+AzureCredentialTypes = AzureKeyCredential | AsyncTokenCredential
+
+# Mapping from media type prefix to the appropriate prebuilt CU analyzer.
+# Used when analyzer_id is None (auto-detect mode).
+MEDIA_TYPE_ANALYZER_MAP: dict[str, str] = {
+    "audio/": "prebuilt-audioSearch",
+    "video/": "prebuilt-videoSearch",
+}
+DEFAULT_ANALYZER: str = "prebuilt-documentSearch"
+
+
+class ContentUnderstandingSettings(TypedDict, total=False):
+    """Settings for ContentUnderstandingContextProvider with auto-loading from environment.
+
+    Settings are resolved in this order: explicit keyword arguments, values from an
+    explicitly provided .env file, then environment variables with the prefix
+    ``AZURE_CONTENTUNDERSTANDING_``.
+
+    Keys:
+        endpoint: Azure AI Foundry endpoint URL.
+            Can be set via environment variable ``AZURE_CONTENTUNDERSTANDING_ENDPOINT``.
+    """
+
+    endpoint: str | None
+
+
+class ContentUnderstandingContextProvider(ContextProvider):
+    """Context provider that analyzes file attachments using Azure Content Understanding.
+
+    Automatically detects supported file attachments in the agent's input,
+    analyzes them via CU, and injects the structured results (markdown, fields)
+    into the LLM context. Supports multiple documents per session with background
+    processing for long-running analyses. Optionally integrates with a vector
+    store backend for ``file_search``-based RAG retrieval on LLM clients that
+    support it.
+
+    Args:
+        endpoint: Azure AI Foundry endpoint URL
+            (e.g., ``"https://<your-foundry-resource>.services.ai.azure.com/"``).
+            Can also be set via environment variable
+            ``AZURE_CONTENTUNDERSTANDING_ENDPOINT``.
+        credential: An ``AzureKeyCredential`` for API key auth or an
+            ``AsyncTokenCredential`` (e.g., ``DefaultAzureCredential``) for
+            Microsoft Entra ID auth.
+        analyzer_id: A prebuilt or custom CU analyzer ID. When ``None``
+            (default), a prebuilt analyzer is chosen automatically based on
+            the file's media type: ``prebuilt-documentSearch`` for documents
+            and images, ``prebuilt-audioSearch`` for audio, and
+            ``prebuilt-videoSearch`` for video.
+            Analyzer reference: https://learn.microsoft.com/azure/ai-services/content-understanding/concepts/analyzer-reference
+            Prebuilt analyzers: https://learn.microsoft.com/azure/ai-services/content-understanding/concepts/prebuilt-analyzers
+        max_wait: Max seconds to wait for analysis before deferring to background.
+            ``None`` waits until complete.
+        output_sections: Which CU output sections to pass to LLM.
+            Defaults to ``["markdown", "fields"]``.
+        file_search: Optional configuration for uploading CU-extracted markdown to
+            a vector store for token-efficient RAG retrieval. When provided, full
+            content injection is replaced by ``file_search`` tool registration.
+            The ``FileSearchConfig`` abstraction is backend-agnostic — use
+            ``FileSearchConfig.from_openai()`` or ``FileSearchConfig.from_foundry()``
+            for supported providers, or supply a custom ``FileSearchBackend``
+            implementation for other vector store services.
+        source_id: Unique identifier for this provider instance, used for message
+            attribution and tool registration. Defaults to ``"azure_contentunderstanding"``.
+        env_file_path: Path to a ``.env`` file for loading settings.
+        env_file_encoding: Encoding of the ``.env`` file.
+
+    Per-file ``additional_properties`` on ``Content`` objects:
+        The provider reads the following keys from
+        ``Content.additional_properties`` (passed via ``Content.from_data()``
+        or ``Content.from_uri()``):
+
+        ``filename`` (str):
+            The document key used for tracking, status, and LLM references.
+            Without a filename, a UUID-based key is generated.
+            Must be unique within a session — uploading a file with a
+            duplicate filename will be rejected and the file will not be
+            analyzed.
+
+        ``analyzer_id`` (str):
+            Per-file analyzer override. Takes priority over the provider-level
+            ``analyzer_id``. Useful for mixing analyzers in the same turn
+            (e.g., ``prebuilt-invoice`` for invoices alongside
+            ``prebuilt-documentSearch`` for general documents).
+
+        ``content_range`` (str):
+            Subset of the input to analyze. For documents, use 1-based page
+            numbers (e.g., ``"1-3"`` for pages 1-3, ``"1,3,5-"`` for pages
+            1, 3, and 5 onward). For audio/video, use milliseconds
+            (e.g., ``"0-60000"`` for the first 60 seconds).
+
+        Example::
+
+            Content.from_data(
+                pdf_bytes,
+                "application/pdf",
+                additional_properties={
+                    "filename": "invoice.pdf",
+                    "analyzer_id": "prebuilt-invoice",
+                    "content_range": "1-3",
+                },
+            )
+    """
+
+    DEFAULT_SOURCE_ID: ClassVar[str] = "azure_contentunderstanding"
+    DEFAULT_MAX_WAIT_SECONDS: ClassVar[float] = 5.0
+
+    def __init__(
+        self,
+        *,
+        endpoint: str | None = None,
+        credential: AzureCredentialTypes | None = None,
+        client: ContentUnderstandingClient | None = None,
+        analyzer_id: str | None = None,
+        max_wait: float | None = DEFAULT_MAX_WAIT_SECONDS,
+        output_sections: list[AnalysisSection] | None = None,
+        file_search: FileSearchConfig | None = None,
+        source_id: str = DEFAULT_SOURCE_ID,
+        env_file_path: str | None = None,
+        env_file_encoding: str | None = None,
+    ) -> None:
+        super().__init__(source_id)
+
+        if client is not None:
+            # Use the pre-built client directly — endpoint/credential are ignored.
+            self._client = client
+            self._owns_client = False
+            self._endpoint = ""
+            self._credential = None
+        else:
+            # Build a new client from endpoint + credential.
+            settings = load_settings(
+                ContentUnderstandingSettings,
+                env_prefix="AZURE_CONTENTUNDERSTANDING_",
+                required_fields=["endpoint"],
+                endpoint=endpoint,
+                env_file_path=env_file_path,
+                env_file_encoding=env_file_encoding,
+            )
+            resolved_endpoint: str = settings["endpoint"]  # type: ignore[assignment]  # validated by load_settings
+
+            if credential is None:
+                raise ValueError(
+                    "Azure credential is required. Provide a 'credential' keyword argument "
+                    "(e.g., AzureKeyCredential or AzureCliCredential), or pass a pre-built "
+                    "'client' (ContentUnderstandingClient) instead."
+                )
+
+            self._endpoint = resolved_endpoint
+            self._credential = credential
+            self._client = ContentUnderstandingClient(
+                self._endpoint, self._credential, user_agent=AGENT_FRAMEWORK_USER_AGENT
+            )
+            self._owns_client = True
+        self.analyzer_id = analyzer_id
+        self.max_wait = max_wait
+        self.output_sections: list[AnalysisSection] = output_sections or ["markdown", "fields"]
+        self.file_search = file_search
+        # Global list of uploaded file IDs — used only by close() for
+        # best-effort cleanup.  The authoritative per-session copy lives in
+        # state["_uploaded_file_ids"] (populated in before_run).  This global
+        # list may contain entries from multiple sessions; that is intentional
+        # for cleanup.
+        self._all_uploaded_file_ids: list[str] = []
+
+    async def __aenter__(self) -> Self:
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """Async context manager exit — cleanup clients."""
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying CU client and clean up resources.
+
+        Uses global tracking lists for best-effort cleanup across all
+        sessions that used this provider instance.
+        """
+        # Clean up uploaded files; the vector store itself is caller-managed.
+        if self.file_search and self._all_uploaded_file_ids:
+            await self._cleanup_uploaded_files()
+        # Only close the client if we created it internally.
+        # When a pre-built client was passed in, the caller owns its lifecycle.
+        if self._owns_client:
+            await self._client.close()
+
+    async def before_run(
+        self,
+        *,
+        agent: SupportsAgentRun,
+        session: AgentSession,
+        context: SessionContext,
+        state: dict[str, Any],
+    ) -> None:
+        """Analyze file attachments and inject results into the LLM context.
+
+        This method is called automatically by the framework before each LLM invocation.
+        """
+        documents: dict[str, DocumentEntry] = state.setdefault("documents", {})
+
+        # Per-session mutable state — isolated per session to prevent cross-session leakage.
+        # _pending_tokens stores serializable continuation tokens (not asyncio.Task objects)
+        # so that state can be persisted to disk/storage by the framework.
+        # Structure: {doc_key: {"continuation_token": <opaque Azure SDK string>,
+        #                       "analyzer_id": <CU analyzer used for this file>}}
+        pending_tokens: dict[str, dict[str, str]] = state.setdefault("_pending_tokens", {})
+        pending_uploads: list[tuple[str, DocumentEntry]] = state.setdefault("_pending_uploads", [])
+
+        # 1. Resolve pending background analyses via continuation tokens
+        await self._resolve_pending_tokens(pending_tokens, pending_uploads, documents, context)
+
+        # 1b. Upload any documents that completed in the background (file_search mode)
+        if pending_uploads:
+            # Use a bounded timeout so before_run() stays responsive and does not block
+            # indefinitely on slow vector store indexing.
+            upload_timeout = getattr(self, "max_wait", None)
+            remaining_uploads: list[tuple[str, DocumentEntry]] = []
+            for upload_key, upload_entry in pending_uploads:
+                try:
+                    if upload_timeout is not None:
+                        await asyncio.wait_for(
+                            self._upload_to_vector_store(upload_key, upload_entry, state=state),
+                            timeout=upload_timeout,
+                        )
+                    else:
+                        await self._upload_to_vector_store(upload_key, upload_entry, state=state)
+                except asyncio.TimeoutError:
+                    # Leave timed-out uploads pending so they can be retried on a later turn.
+                    logger.warning(
+                        "Timed out while uploading document '%s' to vector store; will retry later.",
+                        upload_key,
+                    )
+                    remaining_uploads.append((upload_key, upload_entry))
+                except Exception:
+                    # Log unexpected failures and drop the upload entry; this matches prior
+                    # behavior where all pending uploads were cleared regardless of outcome.
+                    logger.exception(
+                        "Error while uploading document '%s' to vector store; dropping from pending list.",
+                        upload_key,
+                    )
+                    context.extend_messages(
+                        self.source_id,
+                        [
+                            Message(
+                                role="user",
+                                contents=[
+                                    (
+                                        f"Document '{upload_key}' was analyzed but failed to upload "
+                                        "to the vector store. The document content is not available for search."
+                                    )
+                                ],
+                            )
+                        ],
+                    )
+            state["_pending_uploads"] = remaining_uploads
+            pending_uploads = remaining_uploads
+
+        # 2. Detect CU-supported file attachments, strip them from input, and return for analysis
+        new_files = detect_and_strip_files(context)
+
+        # 3. Analyze new files using CU (track elapsed time for combined timeout)
+        file_start_times: dict[str, float] = {}
+        accepted_keys: set[str] = set()  # doc_keys successfully accepted for analysis this turn
+        for doc_key, content_item, binary_data in new_files:
+            # Reject duplicate filenames — re-analyzing would orphan vector store entries
+            if doc_key in documents:
+                logger.warning("Duplicate document key '%s' — skipping (already exists in session).", doc_key)
+                context.extend_messages(
+                    self.source_id,
+                    [
+                        Message(
+                            role="user",
+                            contents=[
+                                (
+                                    f"The user tried to upload '{doc_key}', but a file with that name "
+                                    "was already uploaded earlier in this session. The new upload was rejected "
+                                    "and was not analyzed. Tell the user that a file with the same name "
+                                    "already exists and they need to rename the file before uploading again."
+                                )
+                            ],
+                        )
+                    ],
+                )
+                continue
+            file_start_times[doc_key] = time.monotonic()
+            doc_entry = await self._analyze_file(doc_key, content_item, binary_data, context, pending_tokens)
+            if doc_entry:
+                documents[doc_key] = doc_entry
+                accepted_keys.add(doc_key)
+
+        # 4. Inject content for ready documents and register tools
+        if documents:
+            self._register_tools(documents, context)
+
+        # 5. On upload turns, inject content for docs accepted this turn
+        for doc_key in accepted_keys:
+            entry = documents.get(doc_key)
+            if entry and entry["status"] == DocumentStatus.READY and entry["result"]:
+                # Upload to vector store if file_search is configured
+                if self.file_search:
+                    # Combined timeout: subtract CU analysis time from max_wait
+                    remaining: float | None = None
+                    if self.max_wait is not None:
+                        elapsed = time.monotonic() - file_start_times.get(doc_key, time.monotonic())
+                        remaining = max(0.0, self.max_wait - elapsed)
+                    uploaded = await self._upload_to_vector_store(doc_key, entry, timeout=remaining, state=state)
+                    if uploaded:
+                        context.extend_messages(
+                            self.source_id,
+                            [
+                                Message(
+                                    role="user",
+                                    contents=[
+                                        (
+                                            f"The user just uploaded '{entry['filename']}'. It has been analyzed "
+                                            "using Azure Content Understanding and indexed in a vector store. "
+                                            f"When using file_search, include '{entry['filename']}' in your query "
+                                            "to retrieve content from this specific document."
+                                        )
+                                    ],
+                                )
+                            ],
+                        )
+                    elif entry.get("error"):
+                        # Upload failed (not timeout — actual error)
+                        context.extend_messages(
+                            self.source_id,
+                            [
+                                Message(
+                                    role="user",
+                                    contents=[
+                                        (
+                                            f"Document '{entry['filename']}' was analyzed but failed to upload "
+                                            "to the vector store. The document content is not available for search."
+                                        )
+                                    ],
+                                )
+                            ],
+                        )
+                    else:
+                        # Upload deferred to background (timeout)
+                        context.extend_messages(
+                            self.source_id,
+                            [
+                                Message(
+                                    role="user",
+                                    contents=[
+                                        (
+                                            f"Document '{entry['filename']}' has been analyzed and is being indexed. "
+                                            "Ask about it again in a moment."
+                                        )
+                                    ],
+                                )
+                            ],
+                        )
+                else:
+                    # Without file_search, inject full content into context
+                    context.extend_messages(
+                        self,
+                        [
+                            Message(role="user", contents=[format_result(entry["filename"], entry["result"])]),
+                        ],
+                    )
+                    context.extend_messages(
+                        self.source_id,
+                        [
+                            Message(
+                                role="user",
+                                contents=[
+                                    (
+                                        f"The user just uploaded '{entry['filename']}'."
+                                        " It has been analyzed using Azure Content Understanding."
+                                        " The document content (markdown) and extracted fields"
+                                        " (JSON) are provided above."
+                                        " If the user's question is ambiguous,"
+                                        " prioritize this most recently uploaded document."
+                                        " Use specific field values and cite page numbers"
+                                        " when answering."
+                                    )
+                                ],
+                            )
+                        ],
+                    )
+
+        # 6. Register file_search tool (for LLM clients that support it)
+        if self.file_search:
+            context.extend_tools(
+                self.source_id,
+                [self.file_search.file_search_tool],
+            )
+            context.extend_instructions(
+                self.source_id,
+                "Tool usage guidelines:\n"
+                "- Use file_search ONLY when answering questions about document content.\n"
+                "- Use list_documents() for status queries (e.g. 'list docs', 'what's uploaded?').\n"
+                "- Do NOT call file_search for status queries — it wastes tokens.",
+            )
+
+    # ------------------------------------------------------------------
+    # Analyzer Resolution
+    # ------------------------------------------------------------------
+
+    def _resolve_analyzer_id(self, media_type: str) -> str:
+        """Return the analyzer ID to use for the given media type.
+
+        When ``self.analyzer_id`` is set, it is always returned (explicit
+        override).  Otherwise the media type prefix is matched against the
+        known mapping, falling back to ``prebuilt-documentSearch``.
+        """
+        if self.analyzer_id is not None:
+            return self.analyzer_id
+        for prefix, analyzer in MEDIA_TYPE_ANALYZER_MAP.items():
+            if media_type.startswith(prefix):
+                return analyzer
+        return DEFAULT_ANALYZER
+
+    # ------------------------------------------------------------------
+    # Analysis
+    # ------------------------------------------------------------------
+
+    async def _analyze_file(
+        self,
+        doc_key: str,
+        content: Content,
+        binary_data: bytes | None,
+        context: SessionContext,
+        pending_tokens: dict[str, dict[str, str]] | None = None,
+    ) -> DocumentEntry | None:
+        """Analyze a single file via CU with timeout handling.
+
+        The analyzer is resolved in priority order:
+        1. Per-file override via ``content.additional_properties["analyzer_id"]``
+        2. Provider-level default via ``self.analyzer_id``
+        3. Auto-detect by media type (document/audio/video)
+
+        Returns:
+            A ``DocumentEntry`` (ready, analyzing, or failed), or ``None`` if
+            file data could not be extracted.
+        """
+        media_type = content.media_type or "application/octet-stream"
+        filename = doc_key
+
+        # Per-file analyzer override from additional_properties
+        props = content.additional_properties or {}
+        per_file_analyzer = props.get("analyzer_id")
+        content_range = props.get("content_range")
+        resolved_analyzer = per_file_analyzer or self._resolve_analyzer_id(media_type)
+        t0 = time.monotonic()
+
+        try:
+            # Start CU analysis
+            if content.type == "uri" and content.uri and not content.uri.startswith("data:"):
+                poller = await self._client.begin_analyze(
+                    resolved_analyzer,
+                    inputs=[AnalysisInput(url=content.uri, content_range=content_range)],
+                )
+            elif binary_data:
+                poller = await self._client.begin_analyze_binary(
+                    resolved_analyzer,
+                    binary_input=binary_data,
+                    content_type=media_type,
+                )
+            else:
+                context.extend_messages(
+                    self.source_id,
+                    [Message(role="user", contents=[f"Could not extract file data from '{filename}'."])],
+                )
+                return None
+
+            # Wait with timeout; defer to background polling on timeout.
+            try:
+                result = await asyncio.wait_for(poller.result(), timeout=self.max_wait)
+            except asyncio.TimeoutError:
+                # Save continuation token for resuming on next before_run().
+                # Continuation tokens are serializable strings, so state can
+                # be persisted to disk/storage without issues.
+                token = poller.continuation_token()
+                logger.info("Analysis of '%s' timed out; deferring to background via continuation token.", filename)
+                if pending_tokens is not None:
+                    pending_tokens[doc_key] = {
+                        "continuation_token": token,
+                        "analyzer_id": resolved_analyzer,
+                    }
+                context.extend_messages(
+                    self.source_id,
+                    [
+                        Message(
+                            role="user",
+                            contents=[f"Document '{filename}' is being analyzed. Ask about it again in a moment."],
+                        )
+                    ],
+                )
+                return DocumentEntry(
+                    status=DocumentStatus.ANALYZING,
+                    filename=filename,
+                    media_type=media_type,
+                    analyzer_id=resolved_analyzer,
+                    analyzed_at=None,
+                    analysis_duration_s=None,
+                    upload_duration_s=None,
+                    result=None,
+                    error=None,
+                )
+
+            # Analysis completed within timeout
+            analysis_duration = round(time.monotonic() - t0, 2)
+            extracted = self._extract_sections(result)
+            logger.info("Analyzed '%s' with analyzer '%s' in %.1fs.", filename, resolved_analyzer, analysis_duration)
+            return DocumentEntry(
+                status=DocumentStatus.READY,
+                filename=filename,
+                media_type=media_type,
+                analyzer_id=resolved_analyzer,
+                analyzed_at=datetime.now(tz=timezone.utc).isoformat(),
+                analysis_duration_s=analysis_duration,
+                upload_duration_s=None,
+                result=extracted,
+                error=None,
+            )
+
+        except asyncio.TimeoutError:
+            raise
+        except Exception as e:
+            logger.warning("CU analysis error for '%s': %s", filename, e)
+            context.extend_messages(
+                self.source_id,
+                [Message(role="user", contents=[f"Could not analyze '{filename}': {e}"])],
+            )
+            return DocumentEntry(
+                status=DocumentStatus.FAILED,
+                filename=filename,
+                media_type=media_type,
+                analyzer_id=resolved_analyzer,
+                analyzed_at=datetime.now(tz=timezone.utc).isoformat(),
+                analysis_duration_s=round(time.monotonic() - t0, 2),
+                upload_duration_s=None,
+                result=None,
+                error=str(e),
+            )
+
+    # ------------------------------------------------------------------
+    # Pending Token Resolution
+    # ------------------------------------------------------------------
+
+    async def _resolve_pending_tokens(
+        self,
+        pending_tokens: dict[str, dict[str, str]],
+        pending_uploads: list[tuple[str, DocumentEntry]],
+        documents: dict[str, DocumentEntry],
+        context: SessionContext,
+    ) -> None:
+        """Resume pending CU analyses using serializable continuation tokens.
+
+        When a file's CU analysis exceeds ``max_wait``, a continuation token
+        (an opaque string from the Azure SDK) is saved in ``state`` instead of
+        an ``asyncio.Task``.  This keeps state fully serializable — it can be
+        persisted to disk/storage by the framework.
+
+        On the next ``before_run()`` call, this method resumes each pending
+        operation by passing the token back to ``begin_analyze()``.  If the
+        server-side operation has completed, the result is available
+        immediately; otherwise the token is kept for the next turn.
+        """
+        if not pending_tokens:
+            return
+        logger.info("Resolving %d pending analysis token(s).", len(pending_tokens))
+        completed_keys: list[str] = []
+
+        for doc_key, token_info in pending_tokens.items():
+            entry = documents.get(doc_key)
+            if not entry:
+                completed_keys.append(doc_key)
+                continue
+
+            try:
+                poller = await self._client.begin_analyze(  # type: ignore[call-overload, reportUnknownVariableType]
+                    token_info["analyzer_id"],
+                    continuation_token=token_info["continuation_token"],  # pyright: ignore[reportCallIssue]
+                )
+                # Use wait_for to avoid blocking before_run indefinitely.
+                # poller.done() always returns False for resumed pollers (stale
+                # cached status), so we call poller.result() which polls the server.
+                #
+                # Timeout: at least 10s regardless of max_wait.  The upload-turn
+                # max_wait can be very short (e.g. 5s) for responsiveness, but
+                # on resolution turns the resumed poller needs a network round-trip
+                # to fetch the result.  If the analysis is still running after 10s,
+                # the token is kept and retried on the next turn.
+                MIN_RESOLUTION_TIMEOUT = 10.0
+                resolution_timeout = max(self.max_wait or MIN_RESOLUTION_TIMEOUT, MIN_RESOLUTION_TIMEOUT)
+                try:
+                    result: AnalysisResult = await asyncio.wait_for(
+                        poller.result(),  # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType]
+                        timeout=resolution_timeout,
+                    )  # pyright: ignore[reportUnknownVariableType]
+                except asyncio.TimeoutError:
+                    # Still running — update token and keep for next turn
+                    new_token: str = poller.continuation_token()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
+                    token_info["continuation_token"] = new_token
+                    logger.info("Analysis for '%s' still running; keeping token for next turn.", doc_key)
+                    continue
+
+                completed_keys.append(doc_key)
+                extracted = self._extract_sections(result)  # pyright: ignore[reportUnknownArgumentType]
+                entry["status"] = DocumentStatus.READY
+                entry["analyzed_at"] = datetime.now(tz=timezone.utc).isoformat()
+                entry["result"] = extracted
+                entry["error"] = None
+                logger.info("Background analysis of '%s' completed.", entry["filename"])
+
+                # Inject newly ready content
+                if self.file_search:
+                    pending_uploads.append((doc_key, entry))
+                else:
+                    context.extend_messages(
+                        self,
+                        [
+                            Message(role="user", contents=[format_result(entry["filename"], extracted)]),
+                        ],
+                    )
+                context.extend_messages(
+                    self.source_id,
+                    [
+                        Message(
+                            role="user",
+                            contents=[
+                                f"Document '{entry['filename']}' analysis is now complete."
+                                + (
+                                    " The document is being indexed in the vector store and will become"
+                                    " searchable via file_search shortly."
+                                    if self.file_search
+                                    else " The content is provided above."
+                                )
+                            ],
+                        )
+                    ],
+                )
+
+            except Exception as e:
+                completed_keys.append(doc_key)
+                logger.warning("Background analysis of '%s' failed: %s", entry.get("filename", doc_key), e)
+                entry["status"] = DocumentStatus.FAILED
+                entry["analyzed_at"] = datetime.now(tz=timezone.utc).isoformat()
+                entry["error"] = str(e)
+                context.extend_messages(
+                    self.source_id,
+                    [Message(role="user", contents=[f"Document '{entry['filename']}' analysis failed: {e}"])],
+                )
+
+        for key in completed_keys:
+            del pending_tokens[key]
+
+    # ------------------------------------------------------------------
+    # Output Extraction & Formatting (delegates to _extraction module)
+    # ------------------------------------------------------------------
+
+    def _extract_sections(self, result: AnalysisResult) -> dict[str, object]:
+        return extract_sections(result, self.output_sections)
+
+    # ------------------------------------------------------------------
+    # Tool Registration
+    # ------------------------------------------------------------------
+
+    def _register_tools(
+        self,
+        documents: dict[str, DocumentEntry],
+        context: SessionContext,
+    ) -> None:
+        """Register document tools on the context.
+
+        Only ``list_documents`` is registered — the full document content is
+        already injected into conversation history on the upload turn, so a
+        separate retrieval tool is not needed.
+        """
+        context.extend_tools(
+            self.source_id,
+            [self._make_list_documents_tool(documents)],
+        )
+
+    @staticmethod
+    def _make_list_documents_tool(documents: dict[str, DocumentEntry]) -> FunctionTool:
+        """Create a tool that lists all tracked documents with their status."""
+        docs_ref = documents
+
+        def list_documents() -> str:
+            """List all documents that have been uploaded and their analysis status."""
+            entries: list[dict[str, object]] = []
+            for name, entry in docs_ref.items():
+                entries.append({
+                    "name": name,
+                    "status": entry["status"],
+                    "media_type": entry["media_type"],
+                    "analyzed_at": entry["analyzed_at"],
+                    "analysis_duration_s": entry["analysis_duration_s"],
+                    "upload_duration_s": entry["upload_duration_s"],
+                })
+            return json.dumps(entries, indent=2, default=str)
+
+        return FunctionTool(
+            name="list_documents",
+            description=(
+                "List all documents that have been uploaded in this session "
+                "with their analysis status (analyzing, uploading, ready, or failed)."
+            ),
+            func=list_documents,
+        )
+
+    # ------------------------------------------------------------------
+    # file_search Vector Store Integration
+    # ------------------------------------------------------------------
+
+    async def _upload_to_vector_store(
+        self,
+        doc_key: str,
+        entry: DocumentEntry,
+        *,
+        timeout: float | None = None,
+        state: dict[str, Any] | None = None,
+    ) -> bool:
+        """Upload CU-extracted markdown to the caller's vector store.
+
+        Delegates to the configured ``FileSearchBackend`` (OpenAI, Foundry,
+        or a custom implementation). The upload includes file upload **and**
+        vector store indexing (embedding + ingestion) — ``create_and_poll``
+        waits for the index to be fully ready before returning.
+
+        Args:
+            doc_key: Document identifier.
+            entry: The document entry with extracted results.
+            timeout: Max seconds to wait for upload + indexing. ``None`` waits
+                indefinitely. On timeout the upload is deferred to the
+                per-session ``_pending_uploads`` queue for the next
+                ``before_run()`` call.
+            state: Per-session state dict for tracking uploaded file IDs and
+                pending uploads.
+
+        Returns:
+            True if the upload succeeded, False otherwise.
+        """
+        if not self.file_search:
+            return False
+
+        result = entry.get("result")
+        if not result:
+            return False
+
+        # Upload the full formatted content (markdown + fields + segments),
+        # not just raw markdown — consistent with what non-file_search mode injects.
+        formatted = format_result(entry["filename"], result)
+        if not formatted:
+            return False
+
+        entry["status"] = DocumentStatus.UPLOADING
+        t0 = time.monotonic()
+
+        try:
+            upload_coro = self.file_search.backend.upload_file(
+                self.file_search.vector_store_id, f"{doc_key}.md", formatted.encode("utf-8")
+            )
+            file_id = await asyncio.wait_for(upload_coro, timeout=timeout)
+            upload_duration = round(time.monotonic() - t0, 2)
+            # Track in per-session state and global list (for close() cleanup)
+            if state is not None:
+                state.setdefault("_uploaded_file_ids", []).append(file_id)
+            self._all_uploaded_file_ids.append(file_id)
+            entry["status"] = DocumentStatus.READY
+            entry["upload_duration_s"] = upload_duration
+            logger.info("Uploaded '%s' to vector store in %.1fs (%s bytes).", doc_key, upload_duration, len(formatted))
+            return True
+
+        except asyncio.TimeoutError:
+            logger.info("Vector store upload for '%s' timed out; deferring to background.", doc_key)
+            entry["status"] = DocumentStatus.UPLOADING
+            if state is not None:
+                state.setdefault("_pending_uploads", []).append((doc_key, entry))
+            return False
+
+        except Exception as e:
+            logger.warning("Failed to upload '%s' to vector store: %s", doc_key, e)
+            entry["status"] = DocumentStatus.FAILED
+            entry["upload_duration_s"] = round(time.monotonic() - t0, 2)
+            entry["error"] = f"Vector store upload failed: {e}"
+            return False
+
+    async def _cleanup_uploaded_files(self) -> None:
+        """Delete files uploaded by this provider via the configured backend.
+
+        The vector store itself is caller-managed and is not deleted here.
+        """
+        if not self.file_search:
+            return
+
+        backend = self.file_search.backend
+
+        try:
+            for file_id in self._all_uploaded_file_ids:
+                await backend.delete_file(file_id)
+            self._all_uploaded_file_ids.clear()
+
+        except Exception as e:
+            logger.warning("Failed to clean up uploaded files: %s", e)

python/packages/azure-contentunderstanding/agent_framework_azure_contentunderstanding/_detection.py

@@ -0,0 +1,234 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""File detection utilities for Azure Content Understanding context provider.
+
+Functions for scanning input messages, sniffing MIME types, deriving
+document keys, and extracting binary data from content items.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+import mimetypes
+import re
+import uuid
+
+import filetype
+from agent_framework import Content, SessionContext
+
+logger = logging.getLogger("agent_framework.azure_contentunderstanding")
+
+# MIME types used to match against the resolved media type for routing files to CU analysis.
+# The media type may be provided via Content.media_type or inferred (e.g., via sniffing or filename)
+# when missing or generic (such as application/octet-stream). Only files whose resolved media type is
+# in this set will be processed; others are skipped.
+#
+# Supported input file types:
+# https://learn.microsoft.com/azure/ai-services/content-understanding/service-limits#input-file-limits
+SUPPORTED_MEDIA_TYPES: frozenset[str] = frozenset({
+    # Documents and images
+    "application/pdf",
+    "image/jpeg",
+    "image/png",
+    "image/tiff",
+    "image/bmp",
+    "image/heif",
+    "image/heic",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    # Text
+    "text/plain",
+    "text/html",
+    "text/markdown",
+    "text/rtf",
+    "text/xml",
+    "application/xml",
+    "message/rfc822",
+    "application/vnd.ms-outlook",
+    # Audio
+    "audio/wav",
+    "audio/mpeg",
+    "audio/mp3",
+    "audio/mp4",
+    "audio/m4a",
+    "audio/flac",
+    "audio/ogg",
+    "audio/opus",
+    "audio/webm",
+    "audio/x-ms-wma",
+    "audio/aac",
+    "audio/amr",
+    "audio/3gpp",
+    # Video
+    "video/mp4",
+    "video/quicktime",
+    "video/x-msvideo",
+    "video/webm",
+    "video/x-flv",
+    "video/x-ms-wmv",
+    "video/x-ms-asf",
+    "video/x-matroska",
+})
+
+# Mapping from filetype's MIME output to our canonical SUPPORTED_MEDIA_TYPES values.
+# filetype uses some x-prefixed variants that differ from our set.
+MIME_ALIASES: dict[str, str] = {
+    "audio/x-wav": "audio/wav",
+    "audio/x-flac": "audio/flac",
+    "video/x-m4v": "video/mp4",
+}
+
+
+def detect_and_strip_files(
+    context: SessionContext,
+) -> list[tuple[str, Content, bytes | None]]:
+    """Scan input messages for supported file content and prepare for CU analysis.
+
+    Scans for type ``data`` or ``uri`` content supported by Azure Content
+    Understanding, strips them from messages to prevent raw binary being sent
+    to the LLM, and returns metadata for CU analysis.
+
+    Detected files are tracked via ``doc_key`` (derived from filename, URL,
+    or UUID) and their analysis status is managed in session state.
+
+    When the upstream MIME type is unreliable (``application/octet-stream``
+    or missing), binary content sniffing via ``filetype`` is used to
+    determine the real media type, with ``mimetypes.guess_type`` as a
+    filename-based fallback.
+
+    Returns:
+        List of (doc_key, content_item, binary_data) tuples for files to analyze.
+    """
+    results: list[tuple[str, Content, bytes | None]] = []
+    strip_ids: set[int] = set()
+
+    for msg in context.input_messages:
+        for c in msg.contents:
+            if c.type not in ("data", "uri"):
+                continue
+
+            media_type = c.media_type
+            # Fast path: already a known supported type
+            if media_type and media_type in SUPPORTED_MEDIA_TYPES:
+                binary_data = extract_binary(c)
+                results.append((derive_doc_key(c), c, binary_data))
+                strip_ids.add(id(c))
+                continue
+
+            # Slow path: unreliable MIME — sniff binary content
+            if (not media_type) or (media_type == "application/octet-stream"):
+                binary_data = extract_binary(c)
+                resolved = sniff_media_type(binary_data, c)
+                if resolved and (resolved in SUPPORTED_MEDIA_TYPES):
+                    c.media_type = resolved
+                    results.append((derive_doc_key(c), c, binary_data))
+                    strip_ids.add(id(c))
+
+        # Strip detected files from input so raw binary isn't sent to LLM
+        msg.contents = [c for c in msg.contents if id(c) not in strip_ids]
+
+    return results
+
+
+def sniff_media_type(binary_data: bytes | None, content: Content) -> str | None:
+    """Sniff the actual MIME type from binary data, with filename fallback.
+
+    Uses ``filetype`` (magic-bytes) first, then ``mimetypes.guess_type``
+    on the filename. Normalizes filetype's variant MIME values (e.g.
+    ``audio/x-wav`` -> ``audio/wav``) via ``MIME_ALIASES``.
+    """
+    # 1. Binary sniffing via filetype (needs only first 261 bytes)
+    if binary_data:
+        kind = filetype.guess(binary_data[:262])  # type: ignore[reportUnknownMemberType]
+        if kind:
+            mime: str = kind.mime  # type: ignore[reportUnknownMemberType]
+            return MIME_ALIASES.get(mime, mime)
+
+    # 2. Filename extension fallback — try additional_properties first,
+    # then extract basename from external URL path
+    filename: str | None = None
+    if content.additional_properties:
+        filename = content.additional_properties.get("filename")
+    if not filename and content.uri and not content.uri.startswith("data:"):
+        # Extract basename from URL path (e.g. "https://example.com/report.pdf?v=1" -> "report.pdf")
+        filename = content.uri.split("?")[0].split("#")[0].rsplit("/", 1)[-1]
+    if filename:
+        guessed, _ = mimetypes.guess_type(filename)  # uses file extension to guess MIME type
+        if guessed:
+            return MIME_ALIASES.get(guessed, guessed)
+
+    return None
+
+
+def is_supported_content(content: Content) -> bool:
+    """Check if a content item is a supported file type for CU analysis."""
+    if content.type not in ("data", "uri"):
+        return False
+    media_type = content.media_type
+    if not media_type:
+        return False
+    return media_type in SUPPORTED_MEDIA_TYPES
+
+
+def sanitize_doc_key(raw: str) -> str:
+    """Sanitize a document key to prevent prompt injection.
+
+    Removes control characters (newlines, tabs, etc.), collapses
+    whitespace, strips surrounding whitespace, and caps length at
+    255 characters.
+    """
+    # Remove control characters (C0/C1 controls, including \n, \r, \t)
+    cleaned = re.sub(r"[\x00-\x1f\x7f-\x9f]", "", raw)
+    # Collapse whitespace
+    cleaned = " ".join(cleaned.split())
+    # Cap length
+    return cleaned[:255] if cleaned else f"doc_{uuid.uuid4().hex[:8]}"
+
+
+def derive_doc_key(content: Content) -> str:
+    """Derive a unique document key from content metadata.
+
+    The key is used to track documents in session state. Duplicate keys
+    within a session are rejected (not re-analyzed) to prevent orphaned
+    vector store entries.
+
+    The returned key is sanitized to prevent prompt injection via
+    crafted filenames (control characters removed, length capped).
+
+    Priority: filename > URL basename > generated UUID.
+    """
+    # 1. Filename from additional_properties
+    if content.additional_properties:
+        filename = content.additional_properties.get("filename")
+        if filename and isinstance(filename, str):
+            return sanitize_doc_key(filename)
+
+    # 2. URL path basename for external URIs (e.g. "https://example.com/report.pdf" -> "report.pdf")
+    if content.type == "uri" and content.uri and not content.uri.startswith("data:"):
+        path = content.uri.split("?")[0].split("#")[0]  # strip query params and fragments
+        # rstrip("/") handles trailing slashes (e.g. ".../files/" -> ".../files")
+        # rsplit("/", 1)[-1] splits from the right once to get the last path segment
+        basename = path.rstrip("/").rsplit("/", 1)[-1]
+        if basename:
+            return sanitize_doc_key(basename)
+
+    # 3. Fallback: generate a unique ID for anonymous uploads (no filename, no URL)
+    return f"doc_{uuid.uuid4().hex[:8]}"
+
+
+def extract_binary(content: Content) -> bytes | None:
+    """Extract binary data from a data URI content item.
+
+    Only handles ``data:`` URIs (base64-encoded). Returns ``None`` for
+    external URLs -- those are passed directly to CU via ``begin_analyze``.
+    """
+    if content.uri and content.uri.startswith("data:"):
+        try:
+            _, data_part = content.uri.split(",", 1)
+            return base64.b64decode(data_part)
+        except Exception:
+            logger.warning("Failed to decode base64 data URI")
+            return None
+    return None

python/packages/azure-contentunderstanding/agent_framework_azure_contentunderstanding/_extraction.py

@@ -0,0 +1,297 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Output extraction and formatting for Azure Content Understanding results.
+
+Converts CU ``AnalysisResult`` objects into plain Python dicts suitable
+for LLM consumption, and formats them as human-readable text.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, cast
+
+from azure.ai.contentunderstanding.models import AnalysisResult
+
+from ._models import AnalysisSection
+
+
+def extract_sections(
+    result: AnalysisResult,
+    output_sections: list[AnalysisSection],
+) -> dict[str, object]:
+    """Extract configured sections from a CU analysis result.
+
+    For single-segment results (documents, images, short audio), returns a flat
+    dict with ``markdown`` and ``fields`` at the top level.
+
+    For multi-segment results (e.g. video split into scenes), fields are kept
+    with their respective segments in a ``segments`` list so the LLM can see
+    which fields belong to which part of the content:
+    - ``segments``: list of per-segment dicts with ``markdown``, ``fields``,
+      ``start_time_s``, and ``end_time_s``
+    - ``markdown``: still concatenated at top level for file_search uploads
+    - ``duration_seconds``: computed from the global time span
+    - ``kind`` / ``resolution``: taken from the first segment
+    """
+    extracted: dict[str, object] = {}
+    contents = result.contents
+    if not contents:
+        return extracted
+
+    # --- Warnings from the CU service (ODataV4Format with code/message/target) ---
+    if result.warnings:
+        warnings_out: list[dict[str, str]] = []
+        for w in result.warnings:
+            entry: dict[str, str] = {}
+            code = getattr(w, "code", None)
+            if code:
+                entry["code"] = code
+            msg = getattr(w, "message", None)
+            entry["message"] = msg if msg else str(w)
+            target = getattr(w, "target", None)
+            if target:
+                entry["target"] = target
+            warnings_out.append(entry)
+        extracted["warnings"] = warnings_out
+
+    # --- Media metadata (from first segment) ---
+    first = contents[0]
+    kind = getattr(first, "kind", None)
+    if kind:
+        extracted["kind"] = kind
+    width = getattr(first, "width", None)
+    height = getattr(first, "height", None)
+    if width and height:
+        extracted["resolution"] = f"{width}x{height}"
+
+    # Compute total duration from the global time span of all segments.
+    global_start: int | None = None
+    global_end: int | None = None
+    for content in contents:
+        s = getattr(content, "start_time_ms", None)
+        if s is None:
+            s = getattr(content, "startTimeMs", None)
+        e = getattr(content, "end_time_ms", None)
+        if e is None:
+            e = getattr(content, "endTimeMs", None)
+        if s is not None:
+            global_start = s if global_start is None else min(global_start, s)
+        if e is not None:
+            global_end = e if global_end is None else max(global_end, e)
+    if global_start is not None and global_end is not None:
+        extracted["duration_seconds"] = round((global_end - global_start) / 1000, 1)
+
+    is_multi_segment = len(contents) > 1
+
+    # --- Single-segment: flat output (documents, images, short audio) ---
+    if not is_multi_segment:
+        if "markdown" in output_sections and contents[0].markdown:
+            extracted["markdown"] = contents[0].markdown
+        if "fields" in output_sections and contents[0].fields:
+            fields: dict[str, object] = {}
+            for name, field in contents[0].fields.items():
+                entry_dict: dict[str, object] = {
+                    "type": getattr(field, "type", None),
+                    "value": extract_field_value(field),
+                }
+                confidence = getattr(field, "confidence", None)
+                if confidence is not None:
+                    entry_dict["confidence"] = confidence
+                fields[name] = entry_dict
+            if fields:
+                extracted["fields"] = fields
+        # Content-level category (e.g. from classifier analyzers)
+        category = getattr(contents[0], "category", None)
+        if category:
+            extracted["category"] = category
+        return extracted
+
+    # --- Multi-segment: per-segment output (video scenes, long audio) ---
+    # Each segment keeps its own markdown + fields together so the LLM can
+    # see which fields (e.g. Summary) belong to which part of the content.
+    segments_out: list[dict[str, object]] = []
+    md_parts: list[str] = []  # also collect for top-level concatenated markdown
+
+    for content in contents:
+        seg: dict[str, object] = {}
+
+        # Time range for this segment
+        s = getattr(content, "start_time_ms", None)
+        if s is None:
+            s = getattr(content, "startTimeMs", None)
+        e = getattr(content, "end_time_ms", None)
+        if e is None:
+            e = getattr(content, "endTimeMs", None)
+        if s is not None:
+            seg["start_time_s"] = round(s / 1000, 1)
+        if e is not None:
+            seg["end_time_s"] = round(e / 1000, 1)
+
+        # Per-segment markdown
+        if "markdown" in output_sections and content.markdown:
+            seg["markdown"] = content.markdown
+            md_parts.append(content.markdown)
+
+        # Per-segment fields
+        if "fields" in output_sections and content.fields:
+            seg_fields: dict[str, object] = {}
+            for name, field in content.fields.items():
+                seg_entry: dict[str, object] = {
+                    "type": getattr(field, "type", None),
+                    "value": extract_field_value(field),
+                }
+                confidence = getattr(field, "confidence", None)
+                if confidence is not None:
+                    seg_entry["confidence"] = confidence
+                seg_fields[name] = seg_entry
+            if seg_fields:
+                seg["fields"] = seg_fields
+
+        # Per-segment category (e.g. from classifier analyzers)
+        category = getattr(content, "category", None)
+        if category:
+            seg["category"] = category
+
+        segments_out.append(seg)
+
+    extracted["segments"] = segments_out
+
+    # Top-level concatenated markdown (used by file_search for vector store upload)
+    if md_parts:
+        extracted["markdown"] = "\n\n---\n\n".join(md_parts)
+
+    return extracted
+
+
+def extract_field_value(field: Any) -> object:
+    """Extract the plain Python value from a CU ``ContentField``.
+
+    Uses the SDK's ``.value`` convenience property, which dynamically
+    reads the correct ``value_*`` attribute for each field type.
+    Object and array types are recursively flattened so that the
+    output contains only plain Python primitives (str, int, float,
+    date, dict, list) -- no SDK model objects or raw wire format
+    (``valueNumber``, ``spans``, ``source``, etc.).
+    """
+    field_type = getattr(field, "type", None)
+    raw = getattr(field, "value", None)
+
+    # Object fields -> recursively resolve nested sub-fields
+    if field_type == "object" and raw is not None and isinstance(raw, dict):
+        return {str(k): flatten_field(v) for k, v in cast(dict[str, Any], raw).items()}
+
+    # Array fields -> list of flattened items (each with value + optional confidence)
+    if field_type == "array" and raw is not None and isinstance(raw, list):
+        return [flatten_field(item) for item in cast(list[Any], raw)]
+
+    # Scalar fields (string, number, date, etc.) -- .value returns native Python type
+    return raw
+
+
+def flatten_field(field: Any) -> object:
+    """Flatten a CU ``ContentField`` into a ``{type, value, confidence}`` dict.
+
+    Used for sub-fields inside object and array types to preserve
+    per-field confidence scores. Confidence is omitted when ``None``
+    to reduce token usage.
+    """
+    field_type = getattr(field, "type", None)
+    value = extract_field_value(field)
+    confidence = getattr(field, "confidence", None)
+
+    result: dict[str, object] = {"type": field_type, "value": value}
+    if confidence is not None:
+        result["confidence"] = confidence
+    return result
+
+
+def format_result(filename: str, result: dict[str, object]) -> str:
+    """Format extracted CU result for LLM consumption.
+
+    For multi-segment results (video/audio with ``segments``), each segment's
+    markdown and fields are grouped together so the LLM can see which fields
+    belong to which part of the content.
+    """
+    kind = result.get("kind")
+    is_video = kind == "audioVisual"
+    is_audio = kind == "audio"
+
+    # Header -- media-aware label
+    if is_video:
+        label = "Video analysis"
+    elif is_audio:
+        label = "Audio analysis"
+    else:
+        label = "Document analysis"
+    parts: list[str] = [f'{label} of "{filename}":']
+
+    # Media metadata line (duration, resolution)
+    meta_items: list[str] = []
+    duration = result.get("duration_seconds")
+    if duration is not None:
+        mins, secs = divmod(int(duration), 60)  # type: ignore[call-overload]
+        meta_items.append(f"Duration: {mins}:{secs:02d}")
+    resolution = result.get("resolution")
+    if resolution:
+        meta_items.append(f"Resolution: {resolution}")
+    if meta_items:
+        parts.append(" | ".join(meta_items))
+
+    # --- Multi-segment: format each segment with its own content + fields ---
+    raw_segments = result.get("segments")
+    segments: list[dict[str, object]] = (
+        cast(list[dict[str, object]], raw_segments) if isinstance(raw_segments, list) else []
+    )
+    if segments:
+        for i, seg in enumerate(segments):
+            # Segment header with time range
+            start = seg.get("start_time_s")
+            end = seg.get("end_time_s")
+            if start is not None and end is not None:
+                s_min, s_sec = divmod(int(start), 60)  # type: ignore[call-overload]
+                e_min, e_sec = divmod(int(end), 60)  # type: ignore[call-overload]
+                parts.append(f"\n### Segment {i + 1} ({s_min}:{s_sec:02d} - {e_min}:{e_sec:02d})")
+            else:
+                parts.append(f"\n### Segment {i + 1}")
+
+            # Segment markdown
+            seg_md = seg.get("markdown")
+            if seg_md:
+                parts.append(f"\n```markdown\n{seg_md}\n```")
+
+            # Segment fields
+            seg_fields = seg.get("fields")
+            if isinstance(seg_fields, dict) and seg_fields:
+                fields_json = json.dumps(seg_fields, indent=2, default=str)
+                parts.append(f"\n**Fields:**\n```json\n{fields_json}\n```")
+
+        return "\n".join(parts)
+
+    # --- Single-segment: flat format ---
+    fields_raw = result.get("fields")
+    fields: dict[str, object] = cast(dict[str, object], fields_raw) if isinstance(fields_raw, dict) else {}
+
+    # For audio: promote Summary field as prose before markdown
+    if is_audio and fields:
+        summary_field = fields.get("Summary")
+        if isinstance(summary_field, dict):
+            sf = cast(dict[str, object], summary_field)
+            if sf.get("value"):
+                parts.append(f"\n## Summary\n\n{sf['value']}")
+
+    # Markdown content
+    markdown = result.get("markdown")
+    if markdown:
+        parts.append(f"\n## Content\n\n```markdown\n{markdown}\n```")
+
+    # Fields section
+    if fields:
+        remaining = dict(fields)
+        if is_audio:
+            remaining = {k: v for k, v in remaining.items() if k != "Summary"}
+        if remaining:
+            fields_json = json.dumps(remaining, indent=2, default=str)
+            parts.append(f"\n## Extracted Fields\n\n```json\n{fields_json}\n```")
+
+    return "\n".join(parts)

python/packages/azure-contentunderstanding/agent_framework_azure_contentunderstanding/_file_search.py

@@ -0,0 +1,101 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""File search backend abstraction for vector store file operations.
+
+Provides a unified interface for uploading CU-extracted content to
+vector stores across different LLM clients. Two implementations:
+
+- ``OpenAIFileSearchBackend`` — for ``OpenAIChatClient`` (Responses API)
+- ``FoundryFileSearchBackend`` — for ``FoundryChatClient`` (Responses API via Azure)
+
+Both share the same OpenAI-compatible vector store file API but differ
+in the file upload ``purpose`` value.
+
+Vector store creation, tool construction, and lifecycle management are
+the caller's responsibility — the backend only handles file upload/delete.
+"""
+
+from __future__ import annotations
+
+import io
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class FileSearchBackend(ABC):
+    """Abstract interface for vector store file operations.
+
+    Implementations handle the differences between OpenAI and Foundry
+    file upload APIs (e.g., different ``purpose`` values).
+
+    Vector store creation, deletion, and ``file_search`` tool construction
+    are **not** part of this interface — those are managed by the caller.
+    """
+
+    @abstractmethod
+    async def upload_file(self, vector_store_id: str, filename: str, content: bytes) -> str:
+        """Upload a file to a vector store and return the file ID."""
+
+    @abstractmethod
+    async def delete_file(self, file_id: str) -> None:
+        """Delete a previously uploaded file by ID."""
+
+
+class _OpenAICompatBackend(FileSearchBackend):
+    """Shared base for OpenAI-compatible file upload backends.
+
+    Both OpenAI and Foundry use the same ``client.files.*`` and
+    ``client.vector_stores.files.*`` API surface. Subclasses only
+    override the file upload ``purpose``.
+    """
+
+    _FILE_PURPOSE: str  # Subclasses must set this
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    async def upload_file(self, vector_store_id: str, filename: str, content: bytes) -> str:
+        uploaded = await self._client.files.create(
+            file=(filename, io.BytesIO(content)),
+            purpose=self._FILE_PURPOSE,
+        )
+        # Use create_and_poll to wait for indexing to complete before returning.
+        # Without this, file_search queries may return no results immediately
+        # after upload because the vector store index isn't ready yet.
+        await self._client.vector_stores.files.create_and_poll(
+            vector_store_id=vector_store_id,
+            file_id=uploaded.id,
+        )
+        return uploaded.id  # type: ignore[no-any-return]
+
+    async def delete_file(self, file_id: str) -> None:
+        await self._client.files.delete(file_id)
+
+
+class OpenAIFileSearchBackend(_OpenAICompatBackend):
+    """File search backend for OpenAI Responses API.
+
+    Use with ``OpenAIChatClient`` or ``AzureOpenAIResponsesClient``.
+    Requires an ``AsyncOpenAI`` or ``AsyncAzureOpenAI`` client.
+
+    Args:
+        client: An async OpenAI client (``AsyncOpenAI`` or ``AsyncAzureOpenAI``)
+            that supports ``client.files.*`` and ``client.vector_stores.*`` APIs.
+    """
+
+    _FILE_PURPOSE = "user_data"
+
+
+class FoundryFileSearchBackend(_OpenAICompatBackend):
+    """File search backend for Azure AI Foundry.
+
+    Use with ``FoundryChatClient``. Requires the OpenAI-compatible client
+    obtained from ``FoundryChatClient.client`` (i.e.,
+    ``project_client.get_openai_client()``).
+
+    Args:
+        client: The OpenAI-compatible async client from a ``FoundryChatClient``
+            (access via ``foundry_client.client``).
+    """
+
+    _FILE_PURPOSE = "assistants"

python/packages/azure-contentunderstanding/agent_framework_azure_contentunderstanding/_models.py

@@ -0,0 +1,115 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Literal, TypedDict
+
+from ._file_search import FileSearchBackend, FoundryFileSearchBackend, OpenAIFileSearchBackend
+
+
+class DocumentStatus(str, Enum):
+    """Analysis lifecycle state of a tracked document."""
+
+    ANALYZING = "analyzing"
+    """CU analysis is in progress (deferred to background)."""
+
+    UPLOADING = "uploading"
+    """Analysis complete; vector store upload + indexing is in progress."""
+
+    READY = "ready"
+    """Analysis (and upload, if applicable) completed successfully."""
+
+    FAILED = "failed"
+    """Analysis or upload failed."""
+
+
+AnalysisSection = Literal["markdown", "fields"]
+"""Which sections of the CU output to pass to the LLM.
+
+- ``"markdown"``: Full document text with tables as HTML, reading order preserved.
+- ``"fields"``: Extracted typed fields with confidence scores (when available).
+"""
+
+
+class DocumentEntry(TypedDict):
+    """Tracks the analysis state of a single document in session state."""
+
+    status: DocumentStatus
+    filename: str
+    media_type: str
+    analyzer_id: str
+    analyzed_at: str | None
+    analysis_duration_s: float | None
+    upload_duration_s: float | None
+    result: dict[str, object] | None
+    error: str | None
+
+
+@dataclass
+class FileSearchConfig:
+    """Configuration for uploading CU-extracted content to an existing vector store.
+
+    When provided to ``ContentUnderstandingContextProvider``, analyzed document
+    markdown is automatically uploaded to the specified vector store and the
+    given ``file_search`` tool is registered on the context. This enables
+    token-efficient RAG retrieval on follow-up turns for large documents.
+
+    The caller is responsible for creating and managing the vector store and
+    the ``file_search`` tool. Use :meth:`from_openai` or :meth:`from_foundry`
+    factory methods for convenience.
+
+    Args:
+        backend: A ``FileSearchBackend`` that handles file upload/delete
+            operations for the target vector store.
+        vector_store_id: The ID of a pre-existing vector store to upload to.
+        file_search_tool: A ``file_search`` tool object created via the LLM
+            client's ``get_file_search_tool()`` factory method. This is
+            registered on the context via ``extend_tools`` so the LLM can
+            retrieve uploaded content.
+    """
+
+    backend: FileSearchBackend
+    vector_store_id: str
+    file_search_tool: Any
+
+    @staticmethod
+    def from_openai(
+        client: Any,
+        *,
+        vector_store_id: str,
+        file_search_tool: Any,
+    ) -> FileSearchConfig:
+        """Create a config for OpenAI Responses API (``OpenAIChatClient``).
+
+        Args:
+            client: An ``AsyncOpenAI`` or ``AsyncAzureOpenAI`` client.
+            vector_store_id: The ID of the vector store to upload to.
+            file_search_tool: Tool from ``OpenAIChatClient.get_file_search_tool()``.
+        """
+        return FileSearchConfig(
+            backend=OpenAIFileSearchBackend(client),
+            vector_store_id=vector_store_id,
+            file_search_tool=file_search_tool,
+        )
+
+    @staticmethod
+    def from_foundry(
+        client: Any,
+        *,
+        vector_store_id: str,
+        file_search_tool: Any,
+    ) -> FileSearchConfig:
+        """Create a config for Azure AI Foundry (``FoundryChatClient``).
+
+        Args:
+            client: The OpenAI-compatible client from ``FoundryChatClient.client``.
+            vector_store_id: The ID of the vector store to upload to.
+            file_search_tool: Tool from ``FoundryChatClient.get_file_search_tool()``.
+        """
+        return FileSearchConfig(
+            backend=FoundryFileSearchBackend(client),
+            vector_store_id=vector_store_id,
+            file_search_tool=file_search_tool,
+        )

python/packages/azure-contentunderstanding/pyproject.toml

@@ -0,0 +1,101 @@
+[project]
+name = "agent-framework-azure-contentunderstanding"
+description = "Azure Content Understanding integration for Microsoft Agent Framework."
+authors = [{ name = "Microsoft", email = "af-support@microsoft.com" }]
+readme = "README.md"
+requires-python = ">=3.10"
+version = "1.0.0a260429"
+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 :: 3 - Alpha",
+  "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",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+    "agent-framework-core>=1.2.2,<2",
+    "agent-framework-foundry>=1.2.2,<2",
+    "azure-ai-contentunderstanding>=1.0.1,<1.1",
+    "aiohttp>=3.9,<4",
+    "filetype>=1.2,<2",
+]
+
+[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"
+timeout = 120
+markers = [
+    "integration: marks tests as integration tests that require external services",
+]
+
+[tool.ruff]
+extend = "../../pyproject.toml"
+
+[tool.ruff.lint.per-file-ignores]
+"**/tests/**" = ["D", "INP", "TD", "ERA001", "RUF", "S"]
+"samples/**" = ["D", "INP", "ERA001", "RUF", "S", "T201", "CPY"]
+
+[tool.coverage.run]
+omit = ["**/__init__.py"]
+
+[tool.pyright]
+extends = "../../pyproject.toml"
+include = ["agent_framework_azure_contentunderstanding"]
+exclude = ['tests']
+
+[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_azure_contentunderstanding"]
+exclude_dirs = ["tests"]
+
+[tool.poe]
+executor.type = "uv"
+include = "../../shared_tasks.toml"
+
+[tool.poe.tasks.mypy]
+help = "Run MyPy for this package."
+cmd = "mypy --config-file $POE_ROOT/pyproject.toml agent_framework_azure_contentunderstanding"
+
+[tool.poe.tasks.test]
+help = "Run the default unit test suite for this package."
+cmd = 'pytest -m "not integration" --cov=agent_framework_azure_contentunderstanding --cov-report=term-missing:skip-covered tests'
+
+[build-system]
+requires = ["flit-core >= 3.11,<4.0"]
+build-backend = "flit_core.buildapi"

python/packages/azure-contentunderstanding/samples/01-get-started/01_document_qa.py

@@ -0,0 +1,117 @@
+# Copyright (c) Microsoft. All rights reserved.
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "agent-framework-azure-contentunderstanding",
+#     "agent-framework-foundry",
+#     "azure-identity",
+# ]
+# ///
+# Run with: uv run packages/azure-contentunderstanding/samples/01-get-started/01_document_qa.py
+
+
+import asyncio
+import os
+from pathlib import Path
+
+from agent_framework import Agent, Content, Message
+from agent_framework.foundry import ContentUnderstandingContextProvider, FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+load_dotenv()
+
+"""
+Document Q&A — PDF upload with CU-powered extraction
+
+This sample demonstrates the simplest CU integration: upload a PDF and
+ask questions about it. Azure Content Understanding extracts structured
+markdown with table preservation — superior to LLM-only vision for
+scanned PDFs, handwritten content, and complex layouts.
+
+Environment variables:
+  FOUNDRY_PROJECT_ENDPOINT                — Azure AI Foundry project endpoint
+  FOUNDRY_MODEL             — Model deployment name (e.g. gpt-4.1)
+  AZURE_CONTENTUNDERSTANDING_ENDPOINT      — CU endpoint URL
+"""
+
+# Path to a sample PDF — uses the shared sample asset if available,
+# otherwise falls back to a public URL
+SAMPLE_PDF_PATH = Path(__file__).resolve().parents[1] / "shared" / "sample_assets" / "invoice.pdf"
+
+
+async def main() -> None:
+    credential = AzureCliCredential()
+
+    # Set up Azure Content Understanding context provider
+    cu = ContentUnderstandingContextProvider(
+        endpoint=os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"],
+        credential=credential,
+        analyzer_id="prebuilt-documentSearch",  # RAG-optimized document analyzer
+        max_wait=None,  # wait until CU analysis finishes (no background deferral)
+    )
+
+    # Set up the LLM client
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+        credential=credential,
+    )
+
+    # Create agent with CU context provider.
+    # The provider extracts document content via CU and injects it into the
+    # LLM context so the agent can answer questions about the document.
+    async with cu:
+        agent = Agent(
+            client=client,
+            name="DocumentQA",
+            instructions=(
+                "You are a helpful document analyst. Use the analyzed document "
+                "content and extracted fields to answer questions precisely."
+            ),
+            context_providers=[cu],
+        )
+
+        # --- Turn 1: Upload PDF and ask a question ---
+        # 4. Upload PDF and ask questions
+        # The CU provider extracts markdown + fields from the PDF and injects
+        # the full content into context so the agent can answer precisely.
+        print("--- Upload PDF and ask questions ---")
+
+        pdf_bytes = SAMPLE_PDF_PATH.read_bytes()
+
+        response = await agent.run(
+            Message(
+                role="user",
+                contents=[
+                    Content.from_text(
+                        "What is this document about? Who is the vendor, and what is the total amount due?"
+                    ),
+                    Content.from_data(
+                        pdf_bytes,
+                        "application/pdf",
+                        # Always provide filename — used as the document key
+                        additional_properties={"filename": SAMPLE_PDF_PATH.name},
+                    ),
+                ],
+            )
+        )
+        usage = response.usage_details or {}
+        print(f"Agent: {response}")
+        print(f"  [Input tokens: {usage.get('input_token_count', 'N/A')}]\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+"""
+Sample output:
+
+--- Upload PDF and ask questions ---
+Agent: This document is an **invoice** for services and fees billed to
+  **MICROSOFT CORPORATION** (Invoice **INV-100**), including line items
+  (e.g., Consulting Services, Document Fee, Printing Fee) and a billing summary.
+  - **Vendor:** **CONTOSO LTD.**
+  - **Total amount due:** **$610.00**
+  [Input tokens: 988]
+"""

python/packages/azure-contentunderstanding/samples/01-get-started/02_multi_turn_session.py

@@ -0,0 +1,143 @@
+# Copyright (c) Microsoft. All rights reserved.
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "agent-framework-azure-contentunderstanding",
+#     "agent-framework-foundry",
+#     "azure-identity",
+# ]
+# ///
+# Run with: uv run packages/azure-contentunderstanding/samples/01-get-started/02_multi_turn_session.py
+
+
+import asyncio
+import os
+from pathlib import Path
+
+from agent_framework import Agent, AgentSession, Content, Message
+from agent_framework.foundry import ContentUnderstandingContextProvider, FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+load_dotenv()
+
+"""
+Multi-Turn Session — Cached results across turns
+
+This sample demonstrates multi-turn document Q&A using an AgentSession.
+The session persists CU analysis results and conversation history across
+turns so the agent can answer follow-up questions about previously
+uploaded documents without re-analyzing them.
+
+Key concepts:
+  - AgentSession keeps CU state and conversation history across agent.run() calls
+  - Turn 1: CU analyzes the PDF and injects full content into context
+  - Turn 2: Unrelated question — agent answers from general knowledge
+  - Turn 3: Detailed question — agent uses document content from conversation
+    history (injected in Turn 1) to answer precisely
+
+Environment variables:
+  FOUNDRY_PROJECT_ENDPOINT                — Azure AI Foundry project endpoint
+  FOUNDRY_MODEL             — Model deployment name (e.g. gpt-4.1)
+  AZURE_CONTENTUNDERSTANDING_ENDPOINT      — CU endpoint URL
+"""
+
+SAMPLE_PDF_PATH = Path(__file__).resolve().parents[1] / "shared" / "sample_assets" / "invoice.pdf"
+
+
+async def main() -> None:
+    # 1. Set up credentials and CU context provider
+    credential = AzureCliCredential()
+
+    cu = ContentUnderstandingContextProvider(
+        endpoint=os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"],
+        credential=credential,
+        analyzer_id="prebuilt-documentSearch",
+        max_wait=None,  # wait until CU analysis finishes (no background deferral)
+    )
+
+    # 2. Set up the LLM client
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+        credential=credential,
+    )
+
+    # 3. Create agent and persistent session
+    async with cu:
+        agent = Agent(
+            client=client,
+            name="DocumentQA",
+            instructions=(
+                "You are a helpful document analyst. Use the analyzed document "
+                "content and extracted fields to answer questions precisely."
+            ),
+            context_providers=[cu],
+        )
+
+        # Create a persistent session — this keeps CU state across turns
+        session = AgentSession()
+
+        # 4. Turn 1: Upload PDF
+        # CU analyzes the PDF and injects full content into context.
+        print("--- Turn 1: Upload PDF ---")
+        pdf_bytes = SAMPLE_PDF_PATH.read_bytes()
+        response = await agent.run(
+            Message(
+                role="user",
+                contents=[
+                    Content.from_text("What is this document about?"),
+                    Content.from_data(
+                        pdf_bytes,
+                        "application/pdf",
+                        additional_properties={"filename": SAMPLE_PDF_PATH.name},
+                    ),
+                ],
+            ),
+            session=session,  # <-- persist state across turns
+        )
+        usage = response.usage_details or {}
+        print(f"Agent: {response}")
+        print(f"  [Input tokens: {usage.get('input_token_count', 'N/A')}]\n")
+
+        # 5. Turn 2: Unrelated question
+        # No document needed — agent answers from general knowledge.
+        print("--- Turn 2: Unrelated question ---")
+        response = await agent.run("What is the capital of France?", session=session)
+        usage = response.usage_details or {}
+        print(f"Agent: {response}")
+        print(f"  [Input tokens: {usage.get('input_token_count', 'N/A')}]\n")
+
+        # 6. Turn 3: Detailed follow-up
+        # The agent answers from the full document content that was injected
+        # into conversation history in Turn 1. No re-analysis or tool call needed.
+        print("--- Turn 3: Detailed follow-up ---")
+        response = await agent.run(
+            "What is the shipping address on the invoice?",
+            session=session,
+        )
+        usage = response.usage_details or {}
+        print(f"Agent: {response}")
+        print(f"  [Input tokens: {usage.get('input_token_count', 'N/A')}]\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+"""
+Sample output:
+
+--- Turn 1: Upload PDF ---
+Agent: This document is an **invoice** from **CONTOSO LTD.** to **MICROSOFT
+  CORPORATION**. Amount Due: $610.00. Invoice INV-100, dated 11/15/2019.
+  [Input tokens: 975]
+
+--- Turn 2: Unrelated question ---
+Agent: Paris.
+  [Input tokens: 1134]
+
+--- Turn 3: Detailed follow-up ---
+Agent: Shipping address (SHIP TO): Microsoft Delivery, 123 Ship St,
+  Redmond WA, 98052.
+  [Input tokens: 1155]
+"""

python/packages/azure-contentunderstanding/samples/01-get-started/03_multimodal_chat.py

@@ -0,0 +1,186 @@
+# Copyright (c) Microsoft. All rights reserved.
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "agent-framework-azure-contentunderstanding",
+#     "agent-framework-foundry",
+#     "azure-identity",
+# ]
+# ///
+# Run with: uv run packages/azure-contentunderstanding/samples/01-get-started/03_multimodal_chat.py
+
+
+import asyncio
+import os
+import time
+from pathlib import Path
+
+from agent_framework import Agent, AgentSession, Content, Message
+from agent_framework.foundry import ContentUnderstandingContextProvider, FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+load_dotenv()
+
+"""
+Multi-Modal Chat — PDF, audio, and video in a single turn
+
+This sample demonstrates CU's multi-modal capability: upload a PDF invoice,
+an audio call recording, and a video file all at once. The provider analyzes
+all three in parallel using the right CU analyzer for each media type.
+
+The provider auto-detects the media type and selects the right CU analyzer:
+  - PDF/images  → prebuilt-documentSearch
+  - Audio       → prebuilt-audioSearch
+  - Video       → prebuilt-videoSearch
+
+Environment variables:
+  FOUNDRY_PROJECT_ENDPOINT                — Azure AI Foundry project endpoint
+  FOUNDRY_MODEL             — Model deployment name (e.g. gpt-4.1)
+  AZURE_CONTENTUNDERSTANDING_ENDPOINT      — CU endpoint URL
+"""
+
+# Local PDF from package assets
+SAMPLE_PDF = Path(__file__).resolve().parents[1] / "shared" / "sample_assets" / "invoice.pdf"
+
+# Public audio/video from Azure CU samples repo (raw GitHub URLs)
+_CU_ASSETS = "https://raw.githubusercontent.com/Azure-Samples/azure-ai-content-understanding-assets/main"
+AUDIO_URL = f"{_CU_ASSETS}/audio/callCenterRecording.mp3"
+VIDEO_URL = f"{_CU_ASSETS}/videos/sdk_samples/FlightSimulator.mp4"
+
+
+async def main() -> None:
+    # 1. Set up credentials and CU context provider
+    credential = AzureCliCredential()
+
+    # No analyzer_id specified — the provider auto-detects from media type:
+    #   PDF/images → prebuilt-documentSearch
+    #   Audio      → prebuilt-audioSearch
+    #   Video      → prebuilt-videoSearch
+    cu = ContentUnderstandingContextProvider(
+        endpoint=os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"],
+        credential=credential,
+        max_wait=None,  # wait until each analysis finishes
+    )
+
+    # 2. Set up the LLM client
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+        credential=credential,
+    )
+
+    # 3. Create agent and session
+    async with cu:
+        agent = Agent(
+            client=client,
+            name="MultiModalAgent",
+            instructions=(
+                "You are a helpful assistant that can analyze documents, audio, "
+                "and video files. Answer questions using the extracted content."
+            ),
+            context_providers=[cu],
+        )
+
+        session = AgentSession()
+
+        # --- Turn 1: Upload all 3 modalities at once ---
+        # The provider analyzes all files in parallel using the appropriate
+        # CU analyzer for each media type. All results are injected into
+        # the same context so the agent can answer about all of them.
+        turn1_prompt = (
+            "I'm uploading three files: an invoice PDF, a call center "
+            "audio recording, and a flight simulator video. "
+            "Give a brief summary of each file."
+        )
+        print("--- Turn 1: Upload PDF + audio + video (parallel analysis) ---")
+        print("  (CU analysis may take a few minutes for these audio/video files...)")
+        print(f"User: {turn1_prompt}")
+        t0 = time.perf_counter()
+        response = await agent.run(
+            Message(
+                role="user",
+                contents=[
+                    Content.from_text(turn1_prompt),
+                    Content.from_data(
+                        SAMPLE_PDF.read_bytes(),
+                        "application/pdf",
+                        additional_properties={"filename": "invoice.pdf"},
+                    ),
+                    Content.from_uri(
+                        AUDIO_URL,
+                        media_type="audio/mp3",
+                        additional_properties={"filename": "callCenterRecording.mp3"},
+                    ),
+                    Content.from_uri(
+                        VIDEO_URL,
+                        media_type="video/mp4",
+                        additional_properties={"filename": "FlightSimulator.mp4"},
+                    ),
+                ],
+            ),
+            session=session,
+        )
+        elapsed = time.perf_counter() - t0
+        usage = response.usage_details or {}
+        print(f"  [Analyzed in {elapsed:.1f}s | Input tokens: {usage.get('input_token_count', 'N/A')}]")
+        print(f"Agent: {response}\n")
+
+        # --- Turn 2: Detail question about the PDF ---
+        turn2_prompt = "What are the line items and their amounts on the invoice?"
+        print("--- Turn 2: PDF detail ---")
+        print(f"User: {turn2_prompt}")
+        response = await agent.run(turn2_prompt, session=session)
+        usage = response.usage_details or {}
+        print(f"  [Input tokens: {usage.get('input_token_count', 'N/A')}]")
+        print(f"Agent: {response}\n")
+
+        # --- Turn 3: Detail question about the audio ---
+        turn3_prompt = "What was the customer's issue in the call recording?"
+        print("--- Turn 3: Audio detail ---")
+        print(f"User: {turn3_prompt}")
+        response = await agent.run(turn3_prompt, session=session)
+        usage = response.usage_details or {}
+        print(f"  [Input tokens: {usage.get('input_token_count', 'N/A')}]")
+        print(f"Agent: {response}\n")
+
+        # --- Turn 4: Detail question about the video ---
+        turn4_prompt = "What key scenes or actions are shown in the flight simulator video?"
+        print("--- Turn 4: Video detail ---")
+        print(f"User: {turn4_prompt}")
+        response = await agent.run(turn4_prompt, session=session)
+        usage = response.usage_details or {}
+        print(f"  [Input tokens: {usage.get('input_token_count', 'N/A')}]")
+        print(f"Agent: {response}\n")
+
+        # --- Turn 5: Cross-document question ---
+        turn5_prompt = (
+            "Across all three files, which one contains financial data, "
+            "which one involves a customer interaction, and which one is "
+            "a visual demonstration?"
+        )
+        print("--- Turn 5: Cross-document question ---")
+        print(f"User: {turn5_prompt}")
+        response = await agent.run(turn5_prompt, session=session)
+        usage = response.usage_details or {}
+        print(f"  [Input tokens: {usage.get('input_token_count', 'N/A')}]")
+        print(f"Agent: {response}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+"""
+Sample output:
+
+--- Turn 1: Upload PDF + audio + video (parallel analysis) ---
+User: I'm uploading three files...
+  (CU analysis may take 1-2 minutes for audio/video files...)
+  [Analyzed in ~94s | Input tokens: ~2939]
+Agent: ### invoice.pdf: An invoice from CONTOSO LTD. to MICROSOFT CORPORATION...
+       ### callCenterRecording.mp3: A customer service call about point balance...
+       ### FlightSimulator.mp4: A clip discussing neural text-to-speech...
+
+--- Turn 2-5: Detail and cross-document questions ---
+(Agent answers from conversation history without re-analysis)
+"""

python/packages/azure-contentunderstanding/samples/01-get-started/04_invoice_processing.py

@@ -0,0 +1,193 @@
+# Copyright (c) Microsoft. All rights reserved.
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "agent-framework-azure-contentunderstanding",
+#     "agent-framework-foundry",
+#     "azure-identity",
+#     "pydantic",
+# ]
+# ///
+# Run with: uv run packages/azure-contentunderstanding/samples/01-get-started/04_invoice_processing.py
+
+
+import asyncio
+import os
+from pathlib import Path
+
+from agent_framework import Agent, AgentSession, Content, Message
+from agent_framework.foundry import ContentUnderstandingContextProvider, FoundryChatClient
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+
+load_dotenv()
+
+"""
+Invoice Processing — Structured output with prebuilt-invoice analyzer
+
+This sample demonstrates CU's structured field extraction combined with
+LLM structured output (Pydantic model). The prebuilt-invoice analyzer extracts
+typed fields (VendorName, InvoiceTotal, DueDate, LineItems, etc.) with
+confidence scores. We use output_sections=["fields"] only (no markdown needed)
+since we want the LLM to produce a structured JSON response from the extracted
+fields, not summarize document text.
+
+Environment variables:
+  FOUNDRY_PROJECT_ENDPOINT                — Azure AI Foundry project endpoint
+  FOUNDRY_MODEL             — Model deployment name (e.g. gpt-4.1)
+  AZURE_CONTENTUNDERSTANDING_ENDPOINT      — CU endpoint URL
+"""
+
+SAMPLE_PDF_PATH = Path(__file__).resolve().parents[1] / "shared" / "sample_assets" / "invoice.pdf"
+
+
+# Structured output model — the LLM will return JSON matching this schema
+# Structured output models — the LLM returns JSON matching this schema.
+#
+# Note: the prebuilt-invoice analyzer extracts an extensive set of fields
+# (VendorName, BillingAddress, ShippingAddress, TaxDetails, PONumber, etc.).
+# This sample defines a simplified schema to extract only the fields of
+# interest to the caller. The LLM maps the full CU field output to this
+# subset automatically.
+# Learn more about prebuilt analyzers: https://learn.microsoft.com/azure/ai-services/content-understanding/concepts/prebuilt-analyzers
+
+
+class LineItem(BaseModel):
+    description: str
+    quantity: float | None = None
+    unit_price: float | None = None
+    amount: float | None = None
+
+
+class LowConfidenceField(BaseModel):
+    field_name: str
+    confidence: float
+
+
+class InvoiceResult(BaseModel):
+    vendor_name: str
+    total_amount: float | None = None
+    currency: str = "USD"
+    due_date: str | None = None
+    line_items: list[LineItem] = Field(default_factory=list)
+    low_confidence_fields: list[LowConfidenceField] = Field(
+        default_factory=list,
+        description="Fields with confidence < 0.8, including their confidence score",
+    )
+
+
+async def main() -> None:
+    # 1. Set up credentials and CU context provider
+    credential = AzureCliCredential()
+
+    # Default analyzer is prebuilt-documentSearch (RAG-optimized).
+    # Per-file override via additional_properties["analyzer_id"] lets us
+    # use prebuilt-invoice for structured field extraction on specific files.
+    #
+    # Only request "fields" (not "markdown") — we want the extracted typed
+    # fields for structured output, not the raw document text.
+    cu = ContentUnderstandingContextProvider(
+        endpoint=os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"],
+        credential=credential,
+        analyzer_id="prebuilt-documentSearch",  # default for all files
+        max_wait=None,  # wait until CU analysis finishes
+        output_sections=["fields"],  # fields only — structured output doesn't need markdown
+    )
+
+    # 2. Set up the LLM client
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+        credential=credential,
+    )
+
+    # 3. Create agent and session
+    async with cu:
+        agent = Agent(
+            client=client,
+            name="InvoiceProcessor",
+            instructions=(
+                "You are an invoice processing assistant. Extract invoice data from "
+                "the provided CU fields (JSON with confidence scores). Return structured "
+                "output matching the requested schema. Flag fields with confidence < 0.8 "
+                "in the low_confidence_fields list."
+            ),
+            context_providers=[cu],
+        )
+
+        session = AgentSession()
+
+        # 4. Upload an invoice PDF — uses structured output (Pydantic model)
+        print("--- Upload Invoice (Structured Output) ---")
+
+        pdf_bytes = SAMPLE_PDF_PATH.read_bytes()
+
+        response = await agent.run(
+            Message(
+                role="user",
+                contents=[
+                    Content.from_text(
+                        "Process this invoice. Extract the vendor name, total amount, due date, and all line items."
+                    ),
+                    Content.from_data(
+                        pdf_bytes,
+                        "application/pdf",
+                        # Per-file analyzer override: use prebuilt-invoice for
+                        # structured field extraction (VendorName, InvoiceTotal, etc.)
+                        # instead of the provider default (prebuilt-documentSearch).
+                        additional_properties={
+                            "filename": SAMPLE_PDF_PATH.name,
+                            "analyzer_id": "prebuilt-invoice",
+                        },
+                    ),
+                ],
+            ),
+            session=session,
+            options={"response_format": InvoiceResult},
+        )
+
+        # Parse the structured output from JSON text
+        try:
+            invoice = InvoiceResult.model_validate_json(response.text)
+            print(f"Vendor: {invoice.vendor_name}")
+            print(f"Total: {invoice.currency} {invoice.total_amount}")
+            print(f"Due date: {invoice.due_date}")
+            print(f"Line items ({len(invoice.line_items)}):")
+            for item in invoice.line_items:
+                print(f"  - {item.description}: {item.amount}")
+            if invoice.low_confidence_fields:
+                print("⚠ Low confidence fields:")
+                for f in invoice.low_confidence_fields:
+                    print(f"  - {f.field_name}: {f.confidence:.3f}")
+        except Exception:
+            print(f"Agent (raw): {response.text}\n")
+
+        # 5. Follow-up: free-text question about the invoice
+        print("\n--- Follow-up (Free Text) ---")
+        response = await agent.run(
+            "What is the payment term? Are there any fields with low confidence?",
+            session=session,
+        )
+        print(f"Agent: {response}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+"""
+Sample output:
+
+--- Upload Invoice (Structured Output) ---
+Vendor: CONTOSO LTD.
+Total: USD 110.0
+Due date: 2019-12-15
+Line items (3):
+  - Consulting Services: 60.0
+  - Document Fee: 30.0
+  - Printing Fee: 10.0
+⚠ Low confidence: VendorName, CustomerName
+
+--- Follow-up (Free Text) ---
+Agent: The payment terms are not explicitly stated on the invoice...
+"""

python/packages/azure-contentunderstanding/samples/01-get-started/05_large_doc_file_search.py

@@ -0,0 +1,166 @@
+# Copyright (c) Microsoft. All rights reserved.
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "agent-framework-azure-contentunderstanding",
+#     "agent-framework-foundry",
+#     "azure-identity",
+# ]
+# ///
+# Run with: uv run packages/azure-contentunderstanding/samples/01-get-started/05_large_doc_file_search.py
+
+
+import asyncio
+import os
+from pathlib import Path
+
+from agent_framework import Agent, AgentSession, Content, Message
+from agent_framework.foundry import (
+    ContentUnderstandingContextProvider,
+    FileSearchConfig,
+    FoundryChatClient,
+)
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+load_dotenv()
+
+"""
+Large Document + file_search RAG — CU extraction + OpenAI vector store
+
+For large documents (100+ pages) or long audio/video, injecting the full
+CU-extracted content into the LLM context is impractical. This sample shows
+how to use the built-in file_search integration: CU extracts markdown and
+automatically uploads it to an OpenAI vector store for token-efficient RAG.
+
+When ``FileSearchConfig`` is provided, the provider:
+  1. Extracts markdown via CU (handles scanned PDFs, audio, video)
+  2. Uploads the extracted markdown to a vector store
+  3. Registers a ``file_search`` tool on the agent context
+  4. Cleans up the vector store on close
+
+Architecture:
+  Large PDF -> CU extracts markdown -> auto-upload to vector store -> file_search
+  Follow-up -> file_search retrieves top-k chunks -> LLM answers
+
+NOTE: Requires an async OpenAI client for vector store operations.
+
+This sample uses a single small invoice PDF for simplicity. In practice,
+you can upload multiple files in the same session (each is indexed
+separately in the vector store), and this pattern is most valuable for
+large documents (up to 300 pages), long audio recordings, or video files
+where full-context injection would exceed the LLM's context window.
+CU supports PDFs up to 300 pages / 200 MB, and audio files up to 300 MB
+— see the full service limits:
+https://learn.microsoft.com/azure/ai-services/content-understanding/service-limits#input-file-limits
+
+Environment variables:
+  FOUNDRY_PROJECT_ENDPOINT                — Azure AI Foundry project endpoint
+  FOUNDRY_MODEL             — Model deployment name (e.g. gpt-4.1)
+  AZURE_CONTENTUNDERSTANDING_ENDPOINT      — CU endpoint URL
+"""
+
+SAMPLE_PDF_PATH = Path(__file__).resolve().parents[1] / "shared" / "sample_assets" / "invoice.pdf"
+
+
+async def main() -> None:
+    # 1. Set up credentials and LLM client
+    credential = AzureCliCredential()
+
+    client = FoundryChatClient(
+        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+        model=os.environ["FOUNDRY_MODEL"],
+        credential=credential,
+    )
+
+    # 2. Get the async OpenAI client from FoundryChatClient for vector store operations
+    openai_client = client.client
+
+    # 3. Create vector store and file_search tool
+    vector_store = await openai_client.vector_stores.create(
+        name="cu_large_doc_demo",
+        expires_after={"anchor": "last_active_at", "days": 1},
+    )
+    file_search_tool = client.get_file_search_tool(vector_store_ids=[vector_store.id])
+
+    # 4. Configure CU provider with file_search integration
+    # When file_search is set, CU-extracted markdown is automatically uploaded
+    # to the vector store and the file_search tool is registered on the context.
+    cu = ContentUnderstandingContextProvider(
+        endpoint=os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"],
+        credential=credential,
+        analyzer_id="prebuilt-documentSearch",
+        max_wait=None,  # wait until CU analysis + vector store upload finishes
+        file_search=FileSearchConfig.from_foundry(
+            openai_client,
+            vector_store_id=vector_store.id,
+            file_search_tool=file_search_tool,
+        ),
+    )
+
+    pdf_bytes = SAMPLE_PDF_PATH.read_bytes()
+
+    # The provider handles everything: CU extraction + vector store upload + file_search tool
+    async with cu:
+        agent = Agent(
+            client=client,
+            name="LargeDocAgent",
+            instructions=(
+                "You are a document analyst. Use the file_search tool to find "
+                "relevant sections from the document and answer precisely. "
+                "Cite specific sections when answering."
+            ),
+            context_providers=[cu],
+        )
+
+        session = AgentSession()
+
+        # Turn 1: Upload — CU extracts and uploads to vector store automatically
+        print("--- Turn 1: Upload document ---")
+        response = await agent.run(
+            Message(
+                role="user",
+                contents=[
+                    Content.from_text("What are the key points in this document?"),
+                    Content.from_data(
+                        pdf_bytes,
+                        "application/pdf",
+                        additional_properties={"filename": SAMPLE_PDF_PATH.name},
+                    ),
+                ],
+            ),
+            session=session,
+        )
+        print(f"Agent: {response}\n")
+
+        # Turn 2: Follow-up — file_search retrieves relevant chunks (token efficient)
+        print("--- Turn 2: Follow-up (RAG) ---")
+        response = await agent.run(
+            "What numbers or financial metrics are mentioned?",
+            session=session,
+        )
+        print(f"Agent: {response}\n")
+
+    # Explicitly delete the vector store created for this sample
+    await openai_client.vector_stores.delete(vector_store.id)
+    print("Done. Vector store deleted.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+"""
+Sample output:
+
+--- Turn 1: Upload document ---
+Agent: An invoice from Contoso Ltd. to Microsoft Corporation (INV-100).
+  Line items: Consulting Services $60, Document Fee $30, Printing Fee $10.
+  Subtotal $100, Sales tax $10, Total $110, Previous balance $500, Amount due $610.
+
+--- Turn 2: Follow-up (RAG) ---
+Agent: Subtotal $100.00, Sales tax $10.00, Total $110.00,
+  Previous unpaid balance $500.00, Amount due $610.00.
+  Line items: 2 hours @ $30 = $60, 3 @ $10 = $30, 10 pages @ $1 = $10.
+
+Done. Vector store cleaned up automatically.
+"""

python/packages/azure-contentunderstanding/samples/02-devui/01-multimodal_agent/README.md

@@ -0,0 +1,33 @@
+# DevUI Multi-Modal Agent
+
+Interactive web UI for uploading and chatting with documents, images, audio, and video using Azure Content Understanding.
+
+## Setup
+
+1. Set environment variables (or create a `.env` file in `python/`):
+   ```bash
+   FOUNDRY_PROJECT_ENDPOINT=https://your-project.api.azureml.ms
+   AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=gpt-4.1
+   AZURE_CONTENTUNDERSTANDING_ENDPOINT=https://your-cu-resource.cognitiveservices.azure.com/
+   ```
+
+2. Log in with Azure CLI:
+   ```bash
+   az login
+   ```
+
+3. Run with DevUI:
+   ```bash
+   uv run poe devui --agent packages/azure-contentunderstanding/samples/devui_multimodal_agent
+   ```
+
+4. Open the DevUI URL in your browser and start uploading files.
+
+## What You Can Do
+
+- **Upload PDFs** — including scanned/image-based PDFs that LLM vision struggles with
+- **Upload images** — handwritten notes, infographics, charts
+- **Upload audio** — meeting recordings, call center calls (transcription with speaker ID)
+- **Upload video** — product demos, training videos (frame extraction + transcription)
+- **Ask questions** across all uploaded documents
+- **Check status** — "which documents are ready?" uses the auto-registered `list_documents()` tool

python/packages/azure-contentunderstanding/samples/02-devui/01-multimodal_agent/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) Microsoft. All rights reserved.
+"""DevUI Multi-Modal Agent with Azure Content Understanding."""
+
+from .agent import agent
+
+__all__ = ["agent"]

python/packages/azure-contentunderstanding/samples/02-devui/01-multimodal_agent/agent.py

@@ -0,0 +1,66 @@
+# Copyright (c) Microsoft. All rights reserved.
+"""DevUI Multi-Modal Agent — file upload + CU-powered analysis.
+
+This agent uses Azure Content Understanding to analyze uploaded files
+(PDFs, scanned documents, handwritten images, audio recordings, video)
+and answer questions about them through the DevUI web interface.
+
+Unlike the standard azure_responses_agent which sends files directly to the LLM,
+this agent uses CU for structured extraction — superior for scanned PDFs,
+handwritten content, audio transcription, and video analysis.
+
+Required environment variables:
+  FOUNDRY_PROJECT_ENDPOINT                 — Azure AI Foundry project endpoint
+  FOUNDRY_MODEL                            — Model deployment name (e.g. gpt-4.1)
+  AZURE_CONTENTUNDERSTANDING_ENDPOINT      — CU endpoint URL
+
+Run with DevUI:
+  uv run poe devui --agent packages/azure-contentunderstanding/samples/devui_multimodal_agent
+"""
+
+import os
+
+from agent_framework import Agent
+from agent_framework.foundry import ContentUnderstandingContextProvider, FoundryChatClient
+from azure.core.credentials import AzureKeyCredential
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# --- Auth ---
+_credential = AzureCliCredential()
+_cu_api_key = os.environ.get("AZURE_CONTENTUNDERSTANDING_API_KEY")
+_cu_credential = AzureKeyCredential(_cu_api_key) if _cu_api_key else _credential
+
+cu = ContentUnderstandingContextProvider(
+    endpoint=os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"],
+    credential=_cu_credential,
+    # max_wait controls how long before_run() waits for CU analysis before
+    # deferring to background.  For interactive DevUI use, a short timeout
+    # (e.g. 5s) keeps the chat responsive — the agent tells the user the
+    # file is still being analyzed and resolves it on the next turn.
+    # Use max_wait=None to always wait for analysis to complete.
+    max_wait=5.0,
+)
+
+client = FoundryChatClient(
+    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+    model=os.environ["FOUNDRY_MODEL"],
+    credential=_credential,
+)
+
+agent = Agent(
+    client=client,
+    name="MultiModalDocAgent",
+    instructions=(
+        "You are a helpful document analysis assistant. "
+        "When a user uploads files, they are automatically analyzed using Azure Content Understanding. "
+        "Use list_documents() to check which documents are ready, pending, or failed "
+        "and to see which files are available for answering questions. "
+        "Tell the user if any documents are still being analyzed. "
+        "You can process PDFs, scanned documents, handwritten images, audio recordings, and video files. "
+        "When answering, cite specific content from the documents."
+    ),
+    context_providers=[cu],
+)

python/packages/azure-contentunderstanding/samples/02-devui/02-file_search_agent/azure_openai_backend/README.md

@@ -0,0 +1,51 @@
+# DevUI File Search Agent
+
+Interactive web UI for uploading and chatting with documents, images, audio, and video using Azure Content Understanding + OpenAI file_search RAG.
+
+## How It Works
+
+1. **Upload** any supported file (PDF, image, audio, video) via the DevUI chat
+2. **CU analyzes** the file — auto-selects the right analyzer per media type
+3. **Markdown extracted** by CU is uploaded to an OpenAI vector store
+4. **file_search** tool is registered — LLM retrieves top-k relevant chunks
+5. **Ask questions** across all uploaded documents with token-efficient RAG
+
+## Setup
+
+1. Set environment variables (or create a `.env` file in `python/`):
+   ```bash
+   FOUNDRY_PROJECT_ENDPOINT=https://your-project.services.ai.azure.com/
+   AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME=gpt-4.1
+   AZURE_CONTENTUNDERSTANDING_ENDPOINT=https://your-cu-resource.services.ai.azure.com/
+   ```
+
+2. Log in with Azure CLI:
+   ```bash
+   az login
+   ```
+
+3. Run with DevUI:
+   ```bash
+   devui packages/azure-contentunderstanding/samples/devui_azure_openai_file_search_agent
+   ```
+
+4. Open the DevUI URL in your browser and start uploading files.
+
+## Supported File Types
+
+| Type | Formats | CU Analyzer (auto-detected) |
+|------|---------|----------------------------|
+| Documents | PDF, DOCX, XLSX, PPTX, HTML, TXT, Markdown | `prebuilt-documentSearch` |
+| Images | JPEG, PNG, TIFF, BMP | `prebuilt-documentSearch` |
+| Audio | WAV, MP3, FLAC, OGG, M4A | `prebuilt-audioSearch` |
+| Video | MP4, MOV, AVI, WebM | `prebuilt-videoSearch` |
+
+## vs. devui_multimodal_agent
+
+| Feature | multimodal_agent | file_search_agent |
+|---------|-----------------|-------------------|
+| CU extraction | ✅ Full content injected | ✅ Content indexed in vector store |
+| RAG | ❌ | ✅ file_search retrieves top-k chunks |
+| Large docs (100+ pages) | ⚠️ May exceed context window | ✅ Token-efficient |
+| Multiple large files | ⚠️ Context overflow risk | ✅ All indexed, searchable |
+| Best for | Small docs, quick inspection | Large docs, multi-file Q&A |

python/packages/azure-contentunderstanding/samples/02-devui/02-file_search_agent/azure_openai_backend/__init__.py

@@ -0,0 +1,6 @@
+# Copyright (c) Microsoft. All rights reserved.
+"""DevUI Multi-Modal Agent with CU + file_search RAG."""
+
+from .agent import agent
+
+__all__ = ["agent"]

python/packages/azure-contentunderstanding/samples/02-devui/02-file_search_agent/azure_openai_backend/agent.py

@@ -0,0 +1,105 @@
+# Copyright (c) Microsoft. All rights reserved.
+"""DevUI Multi-Modal Agent — CU extraction + file_search RAG.
+
+This agent combines Azure Content Understanding with OpenAI file_search
+for token-efficient RAG over large or multi-modal documents.
+
+Upload flow:
+  1. CU extracts high-quality markdown (handles scanned PDFs, audio, video)
+  2. Extracted markdown is auto-uploaded to an OpenAI vector store
+  3. file_search tool is registered so the LLM retrieves top-k chunks
+  4. Vector store is configured to auto-expire after inactivity
+
+This is ideal for large documents (100+ pages), long audio recordings,
+or multiple files in the same conversation where full-context injection
+would exceed the LLM's context window.
+
+Analyzer auto-detection:
+  When no analyzer_id is specified, the provider auto-selects the
+  appropriate CU analyzer based on media type:
+    - Documents/images → prebuilt-documentSearch
+    - Audio            → prebuilt-audioSearch
+    - Video            → prebuilt-videoSearch
+
+Required environment variables:
+  FOUNDRY_PROJECT_ENDPOINT                 — Azure AI Foundry project endpoint
+  FOUNDRY_MODEL                            — Model deployment name (e.g. gpt-4.1)
+  AZURE_CONTENTUNDERSTANDING_ENDPOINT      — CU endpoint URL
+
+Run with DevUI:
+  devui packages/azure-contentunderstanding/samples/devui_azure_openai_file_search_agent
+"""
+
+import os
+
+from agent_framework import Agent
+from agent_framework.foundry import (
+    ContentUnderstandingContextProvider,
+    FileSearchConfig,
+    FoundryChatClient,
+)
+from azure.ai.projects import AIProjectClient
+from azure.core.credentials import AzureKeyCredential
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# --- Auth ---
+_credential = AzureCliCredential()
+_cu_api_key = os.environ.get("AZURE_CONTENTUNDERSTANDING_API_KEY")
+_cu_credential = AzureKeyCredential(_cu_api_key) if _cu_api_key else _credential
+
+_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
+
+# --- LLM client + sync vector store setup ---
+# DevUI loads agent modules synchronously at startup while an event loop is already
+# running, so we cannot use async APIs here. A sync AIProjectClient is used for
+# one-time vector store creation; runtime file uploads use client.client (async).
+client = FoundryChatClient(
+    project_endpoint=_endpoint,
+    model=os.environ["FOUNDRY_MODEL"],
+    credential=_credential,
+)
+
+_sync_project = AIProjectClient(endpoint=_endpoint, credential=_credential)  # type: ignore[arg-type]
+_sync_openai = _sync_project.get_openai_client()
+_vector_store = _sync_openai.vector_stores.create(
+    name="devui_cu_file_search",
+    expires_after={"anchor": "last_active_at", "days": 1},
+)
+_sync_openai.close()
+
+_file_search_tool = client.get_file_search_tool(
+    vector_store_ids=[_vector_store.id],
+    max_num_results=3,  # limit chunks to reduce input token usage
+)
+
+# --- CU context provider with file_search ---
+# client.client is the async OpenAI client used for runtime file uploads.
+# No analyzer_id → auto-selects per media type (documents, audio, video)
+cu = ContentUnderstandingContextProvider(
+    endpoint=os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"],
+    credential=_cu_credential,
+    file_search=FileSearchConfig.from_foundry(
+        client.client,  # reuse the LLM client's internal AsyncAzureOpenAI for file uploads
+        vector_store_id=_vector_store.id,
+        file_search_tool=_file_search_tool,
+    ),
+)
+
+agent = Agent(
+    client=client,
+    name="FileSearchDocAgent",
+    instructions=(
+        "You are a helpful document analysis assistant with RAG capabilities. "
+        "When a user uploads files, they are automatically analyzed using Azure Content Understanding "
+        "and indexed in a vector store for efficient retrieval. "
+        "Analysis takes time (seconds for documents, longer for audio/video) — if a document "
+        "is still pending, let the user know and suggest they ask again shortly. "
+        "You can process PDFs, scanned documents, handwritten images, audio recordings, and video files. "
+        "Multiple files can be uploaded and queried in the same conversation. "
+        "When answering, cite specific content from the documents."
+    ),
+    context_providers=[cu],
+)

python/packages/azure-contentunderstanding/samples/02-devui/02-file_search_agent/foundry_backend/README.md

@@ -0,0 +1,34 @@
+# DevUI Foundry File Search Agent
+
+Interactive web UI for uploading and chatting with documents, images, audio, and video using Azure Content Understanding + Foundry file_search RAG.
+
+This is the **Foundry** variant. For the Azure OpenAI Responses API variant, see `devui_azure_openai_file_search_agent`.
+
+## How It Works
+
+1. **Upload** any supported file (PDF, image, audio, video) via the DevUI chat
+2. **CU analyzes** the file — auto-selects the right analyzer per media type
+3. **Markdown extracted** by CU is uploaded to a Foundry vector store
+4. **file_search** tool is registered — LLM retrieves top-k relevant chunks
+5. **Ask questions** across all uploaded documents with token-efficient RAG
+
+## Setup
+
+1. Set environment variables (or create a `.env` file in `python/`):
+   ```bash
+   FOUNDRY_PROJECT_ENDPOINT=https://your-project.services.ai.azure.com/
+   FOUNDRY_MODEL=gpt-4.1
+   AZURE_CONTENTUNDERSTANDING_ENDPOINT=https://your-cu-resource.services.ai.azure.com/
+   ```
+
+2. Log in with Azure CLI:
+   ```bash
+   az login
+   ```
+
+3. Run with DevUI:
+   ```bash
+   devui packages/azure-contentunderstanding/samples/devui_foundry_file_search_agent
+   ```
+
+4. Open the DevUI URL in your browser and start uploading files.

python/packages/azure-contentunderstanding/samples/02-devui/02-file_search_agent/foundry_backend/__init__.py

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

python/packages/azure-contentunderstanding/samples/02-devui/02-file_search_agent/foundry_backend/agent.py

@@ -0,0 +1,109 @@
+# Copyright (c) Microsoft. All rights reserved.
+"""DevUI Multi-Modal Agent — CU extraction + file_search RAG via Azure AI Foundry.
+
+This agent combines Azure Content Understanding with Foundry's file_search
+for token-efficient RAG over large or multi-modal documents.
+
+Upload flow:
+  1. CU extracts high-quality markdown (handles scanned PDFs, audio, video)
+  2. Extracted markdown is uploaded to a Foundry vector store
+  3. file_search tool is registered so the LLM retrieves top-k chunks
+  4. Uploaded files are cleaned up on server shutdown
+
+This sample uses ``FoundryChatClient`` and ``FoundryFileSearchBackend``.
+For the OpenAI Responses API variant, see ``devui_azure_openai_file_search_agent``.
+
+Analyzer auto-detection:
+  When no analyzer_id is specified, the provider auto-selects the
+  appropriate CU analyzer based on media type:
+    - Documents/images → prebuilt-documentSearch
+    - Audio            → prebuilt-audioSearch
+    - Video            → prebuilt-videoSearch
+
+Required environment variables:
+  FOUNDRY_PROJECT_ENDPOINT                 — Azure AI Foundry project endpoint
+  FOUNDRY_MODEL                            — Model deployment name (e.g. gpt-4.1)
+  AZURE_CONTENTUNDERSTANDING_ENDPOINT      — CU endpoint URL
+
+Run with DevUI:
+  devui packages/azure-contentunderstanding/samples/devui_foundry_file_search_agent
+"""
+
+import os
+
+from agent_framework import Agent
+from agent_framework.foundry import (
+    ContentUnderstandingContextProvider,
+    FileSearchConfig,
+    FoundryChatClient,
+)
+from azure.core.credentials import AzureKeyCredential
+from azure.identity import AzureCliCredential
+from dotenv import load_dotenv
+from openai import AzureOpenAI
+
+load_dotenv()
+
+# --- Auth ---
+# AzureCliCredential for Foundry. CU API key optional if on a different resource.
+_credential = AzureCliCredential()
+_cu_api_key = os.environ.get("AZURE_CONTENTUNDERSTANDING_API_KEY")
+_cu_credential = AzureKeyCredential(_cu_api_key) if _cu_api_key else _credential
+
+# --- Foundry LLM client ---
+client = FoundryChatClient(
+    project_endpoint=os.environ.get("FOUNDRY_PROJECT_ENDPOINT", ""),
+    model=os.environ.get("FOUNDRY_MODEL", ""),
+    credential=_credential,
+)
+
+# --- Create vector store (sync client to avoid event loop conflicts in DevUI) ---
+_token = _credential.get_token("https://ai.azure.com/.default").token
+_sync_openai = AzureOpenAI(
+    azure_endpoint=os.environ.get("FOUNDRY_PROJECT_ENDPOINT", ""),
+    azure_ad_token=_token,
+    api_version="2025-04-01-preview",
+)
+_vector_store = _sync_openai.vector_stores.create(
+    name="devui_cu_foundry_file_search",
+    expires_after={"anchor": "last_active_at", "days": 1},
+)
+_sync_openai.close()
+
+_file_search_tool = client.get_file_search_tool(
+    vector_store_ids=[_vector_store.id],
+    max_num_results=3,  # limit chunks to reduce input token usage
+)
+
+# --- CU context provider with file_search ---
+# No analyzer_id → auto-selects per media type (documents, audio, video)
+cu = ContentUnderstandingContextProvider(
+    endpoint=os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"],
+    credential=_cu_credential,
+    # max_wait is the combined budget for CU analysis + vector store upload.
+    # For file_search mode, 10s gives enough time for small documents to be
+    # analyzed and indexed in one turn.  Larger files (audio, video) will
+    # be deferred to background and resolved on the next turn.
+    max_wait=10.0,
+    file_search=FileSearchConfig.from_foundry(
+        client.client,
+        vector_store_id=_vector_store.id,
+        file_search_tool=_file_search_tool,
+    ),
+)
+
+agent = Agent(
+    client=client,
+    name="FoundryFileSearchDocAgent",
+    instructions=(
+        "You are a helpful document analysis assistant with RAG capabilities. "
+        "When a user uploads files, they are automatically analyzed using Azure Content Understanding "
+        "and indexed in a vector store for efficient retrieval. "
+        "Analysis takes time (seconds for documents, longer for audio/video) — if a document "
+        "is still pending, let the user know and suggest they ask again shortly. "
+        "You can process PDFs, scanned documents, handwritten images, audio recordings, and video files. "
+        "Multiple files can be uploaded and queried in the same conversation. "
+        "When answering, cite specific content from the documents."
+    ),
+    context_providers=[cu],
+)

python/packages/azure-contentunderstanding/samples/README.md

@@ -0,0 +1,39 @@
+# Azure Content Understanding Samples
+
+These samples demonstrate how to use the `agent-framework-azure-contentunderstanding` package to add document, image, audio, and video understanding to your agents.
+
+## Prerequisites
+
+1. Azure CLI logged in: `az login`
+2. Environment variables set (or `.env` file in the `python/` directory):
+   ```
+   FOUNDRY_PROJECT_ENDPOINT=https://your-project.services.ai.azure.com
+   FOUNDRY_MODEL=gpt-4.1
+   AZURE_CONTENTUNDERSTANDING_ENDPOINT=https://your-cu-resource.cognitiveservices.azure.com/
+   ```
+
+## Samples
+
+### 01-get-started — Script samples (easy → advanced)
+
+| # | Sample | Description | Run |
+|---|--------|-------------|-----|
+| 01 | [Document Q&A](01-get-started/01_document_qa.py) | Upload a PDF, ask questions with CU-powered extraction | `uv run samples/01-get-started/01_document_qa.py` |
+| 02 | [Multi-Turn Session](01-get-started/02_multi_turn_session.py) | AgentSession persistence across turns | `uv run samples/01-get-started/02_multi_turn_session.py` |
+| 03 | [Multi-Modal Chat](01-get-started/03_multimodal_chat.py) | PDF + audio + video parallel analysis | `uv run samples/01-get-started/03_multimodal_chat.py` |
+| 04 | [Invoice Processing](01-get-started/04_invoice_processing.py) | Structured field extraction with prebuilt-invoice | `uv run samples/01-get-started/04_invoice_processing.py` |
+| 05 | [Large Doc + file_search](01-get-started/05_large_doc_file_search.py) | CU extraction + OpenAI vector store RAG | `uv run samples/01-get-started/05_large_doc_file_search.py` |
+
+### 02-devui — Interactive web UI samples
+
+| # | Sample | Description | Run |
+|---|--------|-------------|-----|
+| 01 | [Multi-Modal Agent](02-devui/01-multimodal_agent/) | Web UI for file upload + CU-powered chat | `devui samples/02-devui/01-multimodal_agent` |
+| 02a | [file_search (Azure OpenAI backend)](02-devui/02-file_search_agent/azure_openai_backend/) | DevUI with CU + Azure OpenAI vector store | `devui samples/02-devui/02-file_search_agent/azure_openai_backend` |
+| 02b | [file_search (Foundry backend)](02-devui/02-file_search_agent/foundry_backend/) | DevUI with CU + Foundry vector store | `devui samples/02-devui/02-file_search_agent/foundry_backend` |
+
+## Install (preview)
+
+```bash
+pip install --pre agent-framework-azure-contentunderstanding
+```

python/packages/azure-contentunderstanding/tests/cu/conftest.py

@@ -0,0 +1,106 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from azure.ai.contentunderstanding.models import AnalysisResult
+
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+
+
+def _load_fixture(name: str) -> dict[str, Any]:
+    return json.loads((FIXTURES_DIR / name).read_text())  # type: ignore[no-any-return]
+
+
+@pytest.fixture
+def pdf_fixture_raw() -> dict[str, Any]:
+    return _load_fixture("analyze_pdf_result.json")
+
+
+@pytest.fixture
+def pdf_analysis_result(pdf_fixture_raw: dict[str, Any]) -> AnalysisResult:
+    return AnalysisResult(pdf_fixture_raw)
+
+
+@pytest.fixture
+def audio_fixture_raw() -> dict[str, Any]:
+    return _load_fixture("analyze_audio_result.json")
+
+
+@pytest.fixture
+def audio_analysis_result(audio_fixture_raw: dict[str, Any]) -> AnalysisResult:
+    return AnalysisResult(audio_fixture_raw)
+
+
+@pytest.fixture
+def invoice_fixture_raw() -> dict[str, Any]:
+    return _load_fixture("analyze_invoice_result.json")
+
+
+@pytest.fixture
+def invoice_analysis_result(invoice_fixture_raw: dict[str, Any]) -> AnalysisResult:
+    return AnalysisResult(invoice_fixture_raw)
+
+
+@pytest.fixture
+def video_fixture_raw() -> dict[str, Any]:
+    return _load_fixture("analyze_video_result.json")
+
+
+@pytest.fixture
+def video_analysis_result(video_fixture_raw: dict[str, Any]) -> AnalysisResult:
+    return AnalysisResult(video_fixture_raw)
+
+
+@pytest.fixture
+def image_fixture_raw() -> dict[str, Any]:
+    return _load_fixture("analyze_image_result.json")
+
+
+@pytest.fixture
+def image_analysis_result(image_fixture_raw: dict[str, Any]) -> AnalysisResult:
+    return AnalysisResult(image_fixture_raw)
+
+
+@pytest.fixture
+def mock_cu_client() -> AsyncMock:
+    """Create a mock ContentUnderstandingClient."""
+    client = AsyncMock()
+    client.close = AsyncMock()
+    return client
+
+
+def make_mock_poller(result: AnalysisResult) -> AsyncMock:
+    """Create a mock poller that returns the given result immediately."""
+    poller = AsyncMock()
+    poller.result = AsyncMock(return_value=result)
+    poller.continuation_token = MagicMock(return_value="mock_continuation_token")
+    poller.done = MagicMock(return_value=True)
+    return poller
+
+
+def make_slow_poller(result: AnalysisResult, delay: float = 10.0) -> MagicMock:
+    """Create a mock poller that simulates a timeout then eventually returns."""
+    poller = MagicMock()
+
+    async def slow_result() -> AnalysisResult:
+        await asyncio.sleep(delay)
+        return result
+
+    poller.result = slow_result
+    poller.continuation_token = MagicMock(return_value="mock_slow_continuation_token")
+    poller.done = MagicMock(return_value=False)
+    return poller
+
+
+def make_failing_poller(error: Exception) -> AsyncMock:
+    """Create a mock poller that raises an exception."""
+    poller = AsyncMock()
+    poller.result = AsyncMock(side_effect=error)
+    return poller

python/packages/azure-contentunderstanding/tests/cu/fixtures/analyze_audio_result.json

@@ -0,0 +1,13 @@
+{
+  "id": "synthetic-audio-001",
+  "status": "Succeeded",
+  "analyzer_id": "prebuilt-audioSearch",
+  "api_version": "2025-05-01-preview",
+  "created_at": "2026-03-21T10:05:00Z",
+  "contents": [
+    {
+      "markdown": "## Call Center Recording\n\n**Duration:** 2 minutes 15 seconds\n**Speakers:** 2\n\n### Transcript\n\n**Speaker 1 (Agent):** Thank you for calling Contoso support. My name is Sarah. How can I help you today?\n\n**Speaker 2 (Customer):** Hi Sarah, I'm calling about my recent order number ORD-5678. It was supposed to arrive yesterday but I haven't received it.\n\n**Speaker 1 (Agent):** I'm sorry to hear that. Let me look up your order. Can you confirm your name and email address?\n\n**Speaker 2 (Customer):** Sure, it's John Smith, john.smith@example.com.\n\n**Speaker 1 (Agent):** Thank you, John. I can see your order was shipped on March 18th. It looks like there was a delay with the carrier. The updated delivery estimate is March 22nd.\n\n**Speaker 2 (Customer):** That's helpful, thank you. Is there anything I can do to track it?\n\n**Speaker 1 (Agent):** Yes, I'll send you a tracking link to your email right away. Is there anything else I can help with?\n\n**Speaker 2 (Customer):** No, that's all. Thanks for your help.\n\n**Speaker 1 (Agent):** You're welcome! Have a great day.",
+      "fields": {}
+    }
+  ]
+}

python/packages/azure-contentunderstanding/tests/cu/fixtures/analyze_image_result.json

@@ -0,0 +1,857 @@
+{
+  "analyzerId": "prebuilt-documentSearch",
+  "apiVersion": "2025-11-01",
+  "createdAt": "2026-03-21T22:44:21Z",
+  "stringEncoding": "codePoint",
+  "warnings": [],
+  "contents": [
+    {
+      "path": "input1",
+      "markdown": "# Contoso Q1 2025 Financial Summary\n\nTotal revenue for Q1 2025 was $42.7 million, an increase of 18% over Q1 2024.\nOperating expenses were $31.2 million. Net profit was $11.5 million. The largest\nrevenue segment was Cloud Services at $19.3 million, followed by Professional\nServices at $14.8 million and Product Licensing at $8.6 million. Headcount at end of\nQ1 was 1,247 employees across 8 offices worldwide.\n",
+      "fields": {
+        "Summary": {
+          "type": "string",
+          "valueString": "The document provides a financial summary for Contoso in Q1 2025, reporting total revenue of $42.7 million, an 18% increase from Q1 2024. Operating expenses were $31.2 million, resulting in a net profit of $11.5 million. The largest revenue segment was Cloud Services with $19.3 million, followed by Professional Services at $14.8 million and Product Licensing at $8.6 million. The company had 1,247 employees across 8 offices worldwide at the end of Q1.",
+          "spans": [
+            {
+              "offset": 37,
+              "length": 77
+            },
+            {
+              "offset": 115,
+              "length": 80
+            },
+            {
+              "offset": 196,
+              "length": 77
+            },
+            {
+              "offset": 274,
+              "length": 84
+            },
+            {
+              "offset": 359,
+              "length": 50
+            }
+          ],
+          "confidence": 0.592,
+          "source": "D(1,212.0000,334.0000,1394.0000,334.0000,1394.0000,374.0000,212.0000,374.0000);D(1,213.0000,379.0000,1398.0000,379.0000,1398.0000,422.0000,213.0000,422.0000);D(1,212.0000,423.0000,1389.0000,423.0000,1389.0000,464.0000,212.0000,464.0000);D(1,213.0000,468.0000,1453.0000,468.0000,1453.0000,510.0000,213.0000,510.0000);D(1,213.0000,512.0000,1000.0000,512.0000,1000.0000,554.0000,213.0000,554.0000)"
+        }
+      },
+      "kind": "document",
+      "startPageNumber": 1,
+      "endPageNumber": 1,
+      "unit": "pixel",
+      "pages": [
+        {
+          "pageNumber": 1,
+          "angle": -0.0242,
+          "width": 1700,
+          "height": 2200,
+          "spans": [
+            {
+              "offset": 0,
+              "length": 410
+            }
+          ],
+          "words": [
+            {
+              "content": "Contoso",
+              "span": {
+                "offset": 2,
+                "length": 7
+              },
+              "confidence": 0.99,
+              "source": "D(1,214,222,401,222,401,274,214,273)"
+            },
+            {
+              "content": "Q1",
+              "span": {
+                "offset": 10,
+                "length": 2
+              },
+              "confidence": 0.957,
+              "source": "D(1,414,222,473,222,473,275,414,274)"
+            },
+            {
+              "content": "2025",
+              "span": {
+                "offset": 13,
+                "length": 4
+              },
+              "confidence": 0.929,
+              "source": "D(1,494,222,607,222,607,276,494,275)"
+            },
+            {
+              "content": "Financial",
+              "span": {
+                "offset": 18,
+                "length": 9
+              },
+              "confidence": 0.975,
+              "source": "D(1,624,222,819,223,819,277,624,276)"
+            },
+            {
+              "content": "Summary",
+              "span": {
+                "offset": 28,
+                "length": 7
+              },
+              "confidence": 0.991,
+              "source": "D(1,836,223,1050,225,1050,279,836,277)"
+            },
+            {
+              "content": "Total",
+              "span": {
+                "offset": 37,
+                "length": 5
+              },
+              "confidence": 0.996,
+              "source": "D(1,212,335,287,334,288,374,212,373)"
+            },
+            {
+              "content": "revenue",
+              "span": {
+                "offset": 43,
+                "length": 7
+              },
+              "confidence": 0.994,
+              "source": "D(1,299,334,417,334,418,374,299,374)"
+            },
+            {
+              "content": "for",
+              "span": {
+                "offset": 51,
+                "length": 3
+              },
+              "confidence": 0.994,
+              "source": "D(1,427,334,467,334,467,374,427,374)"
+            },
+            {
+              "content": "Q1",
+              "span": {
+                "offset": 55,
+                "length": 2
+              },
+              "confidence": 0.944,
+              "source": "D(1,475,334,515,334,515,374,475,374)"
+            },
+            {
+              "content": "2025",
+              "span": {
+                "offset": 58,
+                "length": 4
+              },
+              "confidence": 0.876,
+              "source": "D(1,528,334,604,334,604,374,529,374)"
+            },
+            {
+              "content": "was",
+              "span": {
+                "offset": 63,
+                "length": 3
+              },
+              "confidence": 0.991,
+              "source": "D(1,613,334,672,334,672,374,613,374)"
+            },
+            {
+              "content": "$",
+              "span": {
+                "offset": 67,
+                "length": 1
+              },
+              "confidence": 0.999,
+              "source": "D(1,681,334,698,334,698,374,681,374)"
+            },
+            {
+              "content": "42.7",
+              "span": {
+                "offset": 68,
+                "length": 4
+              },
+              "confidence": 0.946,
+              "source": "D(1,700,334,765,334,765,374,700,374)"
+            },
+            {
+              "content": "million",
+              "span": {
+                "offset": 73,
+                "length": 7
+              },
+              "confidence": 0.977,
+              "source": "D(1,775,334,867,334,867,374,776,374)"
+            },
+            {
+              "content": ",",
+              "span": {
+                "offset": 80,
+                "length": 1
+              },
+              "confidence": 0.998,
+              "source": "D(1,870,334,877,334,877,374,870,374)"
+            },
+            {
+              "content": "an",
+              "span": {
+                "offset": 82,
+                "length": 2
+              },
+              "confidence": 0.998,
+              "source": "D(1,888,334,922,334,922,374,888,374)"
+            },
+            {
+              "content": "increase",
+              "span": {
+                "offset": 85,
+                "length": 8
+              },
+              "confidence": 0.991,
+              "source": "D(1,934,334,1058,335,1059,374,934,374)"
+            },
+            {
+              "content": "of",
+              "span": {
+                "offset": 94,
+                "length": 2
+              },
+              "confidence": 0.982,
+              "source": "D(1,1069,335,1098,335,1098,374,1069,374)"
+            },
+            {
+              "content": "18",
+              "span": {
+                "offset": 97,
+                "length": 2
+              },
+              "confidence": 0.963,
+              "source": "D(1,1108,335,1142,335,1142,374,1108,374)"
+            },
+            {
+              "content": "%",
+              "span": {
+                "offset": 99,
+                "length": 1
+              },
+              "confidence": 0.998,
+              "source": "D(1,1143,335,1171,335,1171,374,1143,374)"
+            },
+            {
+              "content": "over",
+              "span": {
+                "offset": 101,
+                "length": 4
+              },
+              "confidence": 0.946,
+              "source": "D(1,1181,335,1248,335,1248,374,1181,374)"
+            },
+            {
+              "content": "Q1",
+              "span": {
+                "offset": 106,
+                "length": 2
+              },
+              "confidence": 0.875,
+              "source": "D(1,1256,335,1295,335,1295,374,1256,374)"
+            },
+            {
+              "content": "2024",
+              "span": {
+                "offset": 109,
+                "length": 4
+              },
+              "confidence": 0.683,
+              "source": "D(1,1310,335,1384,335,1384,374,1310,374)"
+            },
+            {
+              "content": ".",
+              "span": {
+                "offset": 113,
+                "length": 1
+              },
+              "confidence": 0.991,
+              "source": "D(1,1385,335,1394,335,1394,374,1385,374)"
+            },
+            {
+              "content": "Operating",
+              "span": {
+                "offset": 115,
+                "length": 9
+              },
+              "confidence": 0.996,
+              "source": "D(1,213,380,358,380,358,422,213,422)"
+            },
+            {
+              "content": "expenses",
+              "span": {
+                "offset": 125,
+                "length": 8
+              },
+              "confidence": 0.997,
+              "source": "D(1,369,380,513,379,513,421,369,421)"
+            },
+            {
+              "content": "were",
+              "span": {
+                "offset": 134,
+                "length": 4
+              },
+              "confidence": 0.998,
+              "source": "D(1,521,379,595,379,595,421,521,421)"
+            },
+            {
+              "content": "$",
+              "span": {
+                "offset": 139,
+                "length": 1
+              },
+              "confidence": 0.999,
+              "source": "D(1,603,379,620,379,620,421,603,421)"
+            },
+            {
+              "content": "31.2",
+              "span": {
+                "offset": 140,
+                "length": 4
+              },
+              "confidence": 0.938,
+              "source": "D(1,623,379,686,379,686,421,623,421)"
+            },
+            {
+              "content": "million",
+              "span": {
+                "offset": 145,
+                "length": 7
+              },
+              "confidence": 0.913,
+              "source": "D(1,696,379,790,379,790,421,696,421)"
+            },
+            {
+              "content": ".",
+              "span": {
+                "offset": 152,
+                "length": 1
+              },
+              "confidence": 0.975,
+              "source": "D(1,793,379,800,379,800,421,793,421)"
+            },
+            {
+              "content": "Net",
+              "span": {
+                "offset": 154,
+                "length": 3
+              },
+              "confidence": 0.976,
+              "source": "D(1,811,379,862,379,862,420,811,421)"
+            },
+            {
+              "content": "profit",
+              "span": {
+                "offset": 158,
+                "length": 6
+              },
+              "confidence": 0.993,
+              "source": "D(1,871,379,947,379,947,420,871,420)"
+            },
+            {
+              "content": "was",
+              "span": {
+                "offset": 165,
+                "length": 3
+              },
+              "confidence": 0.997,
+              "source": "D(1,954,379,1012,379,1012,420,953,420)"
+            },
+            {
+              "content": "$",
+              "span": {
+                "offset": 169,
+                "length": 1
+              },
+              "confidence": 0.998,
+              "source": "D(1,1021,379,1039,379,1039,420,1021,420)"
+            },
+            {
+              "content": "11.5",
+              "span": {
+                "offset": 170,
+                "length": 4
+              },
+              "confidence": 0.954,
+              "source": "D(1,1043,379,1106,379,1106,421,1043,420)"
+            },
+            {
+              "content": "million",
+              "span": {
+                "offset": 175,
+                "length": 7
+              },
+              "confidence": 0.837,
+              "source": "D(1,1118,379,1208,379,1208,421,1118,421)"
+            },
+            {
+              "content": ".",
+              "span": {
+                "offset": 182,
+                "length": 1
+              },
+              "confidence": 0.978,
+              "source": "D(1,1210,379,1217,379,1217,421,1210,421)"
+            },
+            {
+              "content": "The",
+              "span": {
+                "offset": 184,
+                "length": 3
+              },
+              "confidence": 0.949,
+              "source": "D(1,1228,379,1285,379,1285,421,1228,421)"
+            },
+            {
+              "content": "largest",
+              "span": {
+                "offset": 188,
+                "length": 7
+              },
+              "confidence": 0.978,
+              "source": "D(1,1295,379,1398,379,1398,421,1295,421)"
+            },
+            {
+              "content": "revenue",
+              "span": {
+                "offset": 196,
+                "length": 7
+              },
+              "confidence": 0.995,
+              "source": "D(1,212,425,334,425,334,464,212,464)"
+            },
+            {
+              "content": "segment",
+              "span": {
+                "offset": 204,
+                "length": 7
+              },
+              "confidence": 0.996,
+              "source": "D(1,344,425,472,424,472,464,344,464)"
+            },
+            {
+              "content": "was",
+              "span": {
+                "offset": 212,
+                "length": 3
+              },
+              "confidence": 0.998,
+              "source": "D(1,480,424,541,424,541,464,480,464)"
+            },
+            {
+              "content": "Cloud",
+              "span": {
+                "offset": 216,
+                "length": 5
+              },
+              "confidence": 0.997,
+              "source": "D(1,550,424,636,424,637,464,551,464)"
+            },
+            {
+              "content": "Services",
+              "span": {
+                "offset": 222,
+                "length": 8
+              },
+              "confidence": 0.995,
+              "source": "D(1,647,424,774,424,774,464,647,464)"
+            },
+            {
+              "content": "at",
+              "span": {
+                "offset": 231,
+                "length": 2
+              },
+              "confidence": 0.996,
+              "source": "D(1,784,424,812,424,812,464,784,464)"
+            },
+            {
+              "content": "$",
+              "span": {
+                "offset": 234,
+                "length": 1
+              },
+              "confidence": 0.998,
+              "source": "D(1,820,424,837,424,837,464,820,464)"
+            },
+            {
+              "content": "19.3",
+              "span": {
+                "offset": 235,
+                "length": 4
+              },
+              "confidence": 0.879,
+              "source": "D(1,840,424,903,423,903,463,840,464)"
+            },
+            {
+              "content": "million",
+              "span": {
+                "offset": 240,
+                "length": 7
+              },
+              "confidence": 0.876,
+              "source": "D(1,915,423,1006,423,1006,463,915,463)"
+            },
+            {
+              "content": ",",
+              "span": {
+                "offset": 247,
+                "length": 1
+              },
+              "confidence": 0.999,
+              "source": "D(1,1008,423,1015,423,1015,463,1008,463)"
+            },
+            {
+              "content": "followed",
+              "span": {
+                "offset": 249,
+                "length": 8
+              },
+              "confidence": 0.978,
+              "source": "D(1,1026,423,1148,424,1148,463,1026,463)"
+            },
+            {
+              "content": "by",
+              "span": {
+                "offset": 258,
+                "length": 2
+              },
+              "confidence": 0.986,
+              "source": "D(1,1160,424,1194,424,1194,463,1160,463)"
+            },
+            {
+              "content": "Professional",
+              "span": {
+                "offset": 261,
+                "length": 12
+              },
+              "confidence": 0.965,
+              "source": "D(1,1204,424,1389,424,1389,463,1204,463)"
+            },
+            {
+              "content": "Services",
+              "span": {
+                "offset": 274,
+                "length": 8
+              },
+              "confidence": 0.991,
+              "source": "D(1,213,469,341,469,341,510,213,510)"
+            },
+            {
+              "content": "at",
+              "span": {
+                "offset": 283,
+                "length": 2
+              },
+              "confidence": 0.997,
+              "source": "D(1,352,469,380,469,380,510,352,510)"
+            },
+            {
+              "content": "$",
+              "span": {
+                "offset": 286,
+                "length": 1
+              },
+              "confidence": 0.998,
+              "source": "D(1,388,469,405,469,405,510,388,510)"
+            },
+            {
+              "content": "14.8",
+              "span": {
+                "offset": 287,
+                "length": 4
+              },
+              "confidence": 0.973,
+              "source": "D(1,410,469,472,469,472,510,410,510)"
+            },
+            {
+              "content": "million",
+              "span": {
+                "offset": 292,
+                "length": 7
+              },
+              "confidence": 0.987,
+              "source": "D(1,483,469,575,469,575,510,483,510)"
+            },
+            {
+              "content": "and",
+              "span": {
+                "offset": 300,
+                "length": 3
+              },
+              "confidence": 0.999,
+              "source": "D(1,585,469,638,469,638,510,585,510)"
+            },
+            {
+              "content": "Product",
+              "span": {
+                "offset": 304,
+                "length": 7
+              },
+              "confidence": 0.995,
+              "source": "D(1,652,469,765,469,765,510,652,510)"
+            },
+            {
+              "content": "Licensing",
+              "span": {
+                "offset": 312,
+                "length": 9
+              },
+              "confidence": 0.993,
+              "source": "D(1,777,469,914,469,914,510,777,510)"
+            },
+            {
+              "content": "at",
+              "span": {
+                "offset": 322,
+                "length": 2
+              },
+              "confidence": 0.998,
+              "source": "D(1,925,469,953,469,953,510,925,510)"
+            },
+            {
+              "content": "$",
+              "span": {
+                "offset": 325,
+                "length": 1
+              },
+              "confidence": 0.998,
+              "source": "D(1,961,469,978,469,978,510,961,510)"
+            },
+            {
+              "content": "8.6",
+              "span": {
+                "offset": 326,
+                "length": 3
+              },
+              "confidence": 0.958,
+              "source": "D(1,980,469,1025,469,1025,510,980,510)"
+            },
+            {
+              "content": "million",
+              "span": {
+                "offset": 330,
+                "length": 7
+              },
+              "confidence": 0.908,
+              "source": "D(1,1036,469,1128,468,1128,510,1036,510)"
+            },
+            {
+              "content": ".",
+              "span": {
+                "offset": 337,
+                "length": 1
+              },
+              "confidence": 0.987,
+              "source": "D(1,1130,468,1137,468,1137,510,1130,510)"
+            },
+            {
+              "content": "Headcount",
+              "span": {
+                "offset": 339,
+                "length": 9
+              },
+              "confidence": 0.934,
+              "source": "D(1,1150,468,1310,468,1310,510,1150,510)"
+            },
+            {
+              "content": "at",
+              "span": {
+                "offset": 349,
+                "length": 2
+              },
+              "confidence": 0.993,
+              "source": "D(1,1318,468,1348,468,1348,510,1318,510)"
+            },
+            {
+              "content": "end",
+              "span": {
+                "offset": 352,
+                "length": 3
+              },
+              "confidence": 0.947,
+              "source": "D(1,1355,468,1410,468,1410,510,1355,510)"
+            },
+            {
+              "content": "of",
+              "span": {
+                "offset": 356,
+                "length": 2
+              },
+              "confidence": 0.974,
+              "source": "D(1,1419,468,1453,468,1453,509,1419,509)"
+            },
+            {
+              "content": "Q1",
+              "span": {
+                "offset": 359,
+                "length": 2
+              },
+              "confidence": 0.931,
+              "source": "D(1,213,512,252,512,252,554,213,554)"
+            },
+            {
+              "content": "was",
+              "span": {
+                "offset": 362,
+                "length": 3
+              },
+              "confidence": 0.847,
+              "source": "D(1,267,512,326,512,326,554,267,554)"
+            },
+            {
+              "content": "1,247",
+              "span": {
+                "offset": 366,
+                "length": 5
+              },
+              "confidence": 0.523,
+              "source": "D(1,338,512,419,512,419,554,338,554)"
+            },
+            {
+              "content": "employees",
+              "span": {
+                "offset": 372,
+                "length": 9
+              },
+              "confidence": 0.972,
+              "source": "D(1,429,513,591,512,591,554,429,554)"
+            },
+            {
+              "content": "across",
+              "span": {
+                "offset": 382,
+                "length": 6
+              },
+              "confidence": 0.972,
+              "source": "D(1,601,512,697,512,697,554,601,554)"
+            },
+            {
+              "content": "8",
+              "span": {
+                "offset": 389,
+                "length": 1
+              },
+              "confidence": 0.946,
+              "source": "D(1,708,512,725,512,725,553,708,554)"
+            },
+            {
+              "content": "offices",
+              "span": {
+                "offset": 391,
+                "length": 7
+              },
+              "confidence": 0.95,
+              "source": "D(1,736,512,831,512,831,553,736,553)"
+            },
+            {
+              "content": "worldwide",
+              "span": {
+                "offset": 399,
+                "length": 9
+              },
+              "confidence": 0.988,
+              "source": "D(1,840,512,989,512,989,552,840,553)"
+            },
+            {
+              "content": ".",
+              "span": {
+                "offset": 408,
+                "length": 1
+              },
+              "confidence": 0.996,
+              "source": "D(1,991,512,1000,512,1000,552,991,552)"
+            }
+          ],
+          "lines": [
+            {
+              "content": "Contoso Q1 2025 Financial Summary",
+              "source": "D(1,214,221,1050,225,1050,279,213,273)",
+              "span": {
+                "offset": 2,
+                "length": 33
+              }
+            },
+            {
+              "content": "Total revenue for Q1 2025 was $42.7 million, an increase of 18% over Q1 2024.",
+              "source": "D(1,212,334,1394,335,1394,374,212,374)",
+              "span": {
+                "offset": 37,
+                "length": 77
+              }
+            },
+            {
+              "content": "Operating expenses were $31.2 million. Net profit was $11.5 million. The largest",
+              "source": "D(1,213,379,1398,378,1398,421,213,422)",
+              "span": {
+                "offset": 115,
+                "length": 80
+              }
+            },
+            {
+              "content": "revenue segment was Cloud Services at $19.3 million, followed by Professional",
+              "source": "D(1,212,424,1389,423,1389,463,212,464)",
+              "span": {
+                "offset": 196,
+                "length": 77
+              }
+            },
+            {
+              "content": "Services at $14.8 million and Product Licensing at $8.6 million. Headcount at end of",
+              "source": "D(1,213,469,1453,468,1453,510,213,511)",
+              "span": {
+                "offset": 274,
+                "length": 84
+              }
+            },
+            {
+              "content": "Q1 was 1,247 employees across 8 offices worldwide.",
+              "source": "D(1,213,512,1000,512,1000,554,213,554)",
+              "span": {
+                "offset": 359,
+                "length": 50
+              }
+            }
+          ]
+        }
+      ],
+      "paragraphs": [
+        {
+          "role": "title",
+          "content": "Contoso Q1 2025 Financial Summary",
+          "source": "D(1,214,219,1050,225,1050,279,213,273)",
+          "span": {
+            "offset": 0,
+            "length": 35
+          }
+        },
+        {
+          "content": "Total revenue for Q1 2025 was $42.7 million, an increase of 18% over Q1 2024. Operating expenses were $31.2 million. Net profit was $11.5 million. The largest revenue segment was Cloud Services at $19.3 million, followed by Professional Services at $14.8 million and Product Licensing at $8.6 million. Headcount at end of Q1 was 1,247 employees across 8 offices worldwide.",
+          "source": "D(1,212,334,1453,333,1454,553,212,554)",
+          "span": {
+            "offset": 37,
+            "length": 372
+          }
+        }
+      ],
+      "sections": [
+        {
+          "span": {
+            "offset": 0,
+            "length": 409
+          },
+          "elements": [
+            "/paragraphs/0",
+            "/paragraphs/1"
+          ]
+        }
+      ],
+      "analyzerId": "prebuilt-documentSearch",
+      "mimeType": "image/png"
+    }
+  ]
+}

python/packages/azure-contentunderstanding/tests/cu/fixtures/analyze_invoice_result.json

@@ -0,0 +1,114 @@
+{
+  "analyzerId": "prebuilt-invoice",
+  "apiVersion": "2025-11-01",
+  "createdAt": "2026-03-21T22:44:33Z",
+  "stringEncoding": "codePoint",
+  "warnings": [],
+  "contents": [
+    {
+      "markdown": "# Master Services Agreement\n\nClient: Alpine Industries Inc.\n\nContract Reference: MSA-2025-ALP-00847\n\nEffective Date: January 15, 2025\nPrepared for: Robert Chen, Chief Executive Officer, Alpine Industries Inc.\n\nAddress: 742 Evergreen Blvd, Denver, CO 80203\n\nThis Master Services Agreement (the 'Agreement') is entered into by and between Alpine Industries\nInc. (the 'Client') and TechServe Global Partners (the 'Provider'). This agreement governs the provision\nof managed technology services as descri",
+      "fields": {
+        "VendorName": {
+          "type": "string",
+          "valueString": "TechServe Global Partners",
+          "confidence": 0.71
+        },
+        "DueDate": {
+          "type": "date",
+          "valueDate": "2025-02-15",
+          "confidence": 0.793
+        },
+        "InvoiceDate": {
+          "type": "date",
+          "valueDate": "2025-01-15",
+          "confidence": 0.693
+        },
+        "InvoiceId": {
+          "type": "string",
+          "valueString": "INV-100",
+          "confidence": 0.489
+        },
+        "AmountDue": {
+          "type": "object",
+          "valueObject": {
+            "Amount": {
+              "type": "number",
+              "valueNumber": 610,
+              "confidence": 0.758
+            },
+            "CurrencyCode": {
+              "type": "string",
+              "valueString": "USD"
+            }
+          }
+        },
+        "SubtotalAmount": {
+          "type": "object",
+          "valueObject": {
+            "Amount": {
+              "type": "number",
+              "valueNumber": 100,
+              "confidence": 0.902
+            },
+            "CurrencyCode": {
+              "type": "string",
+              "valueString": "USD"
+            }
+          }
+        },
+        "LineItems": {
+          "type": "array",
+          "valueArray": [
+            {
+              "type": "object",
+              "valueObject": {
+                "Description": {
+                  "type": "string",
+                  "valueString": "Consulting Services",
+                  "confidence": 0.664
+                },
+                "Quantity": {
+                  "type": "number",
+                  "valueNumber": 2,
+                  "confidence": 0.957
+                },
+                "UnitPrice": {
+                  "type": "object",
+                  "valueObject": {
+                    "Amount": {
+                      "type": "number",
+                      "valueNumber": 30,
+                      "confidence": 0.956
+                    },
+                    "CurrencyCode": {
+                      "type": "string",
+                      "valueString": "USD"
+                    }
+                  }
+                }
+              }
+            },
+            {
+              "type": "object",
+              "valueObject": {
+                "Description": {
+                  "type": "string",
+                  "valueString": "Document Fee",
+                  "confidence": 0.712
+                },
+                "Quantity": {
+                  "type": "number",
+                  "valueNumber": 3,
+                  "confidence": 0.939
+                }
+              }
+            }
+          ]
+        }
+      },
+      "kind": "document",
+      "startPageNumber": 1,
+      "endPageNumber": 100
+    }
+  ]
+}

python/packages/azure-contentunderstanding/tests/cu/fixtures/analyze_pdf_result.json

@@ -0,0 +1,23 @@
+{
+  "analyzerId": "prebuilt-documentSearch",
+  "apiVersion": "2025-11-01",
+  "createdAt": "2026-03-21T22:44:09Z",
+  "contents": [
+    {
+      "path": "input1",
+      "markdown": "# Contoso Q1 2025 Financial Summary\n\nTotal revenue for Q1 2025 was $42.7 million, an increase of 18% over Q1 2024.\nOperating expenses were $31.2 million. Net profit was $11.5 million. The largest\nrevenue segment was Cloud Services at $19.3 million, followed by Professional\nServices at $14.8 million and Product Licensing at $8.6 million. Headcount at end of\nQ1 was 1,247 employees across 8 offices worldwide.\n\n<!-- PageBreak -->\n\n\n# Contoso Q2 2025 Financial Summary\n\nTotal revenue for Q2 2025 was $48.1 million, an increase of 22% over Q2 2024.\nOperating expenses were $33.9 million. Net profit was $14.2 million. Cloud Services\ngrew to $22.5 million, Professional Services was $15.7 million, and Product Licensing\nwas $9.9 million. The company opened a new office in Tokyo, bringing the total to 9\noffices. Headcount grew to 1,389 employees.\n\n<!-- PageBreak -->\n\n\n## Contoso Product Roadmap 2025\n\nThree major product launches are planned for 2025: (1) Contoso CloudVault - an\nenterprise document storage solution, launching August 2025, with an expected price\nof $29.99/user/month. (2) Contoso DataPulse - a real-time analytics dashboard,\nlaunching October 2025. (3) Contoso SecureLink - a zero-trust networking product,\nlaunching December 2025. Total R&D; budget for 2025 is $18.4 million.\n\n<!-- PageBreak -->\n\n\n# Contoso Employee Satisfaction Survey Results\n\nThe annual employee satisfaction survey was completed in March 2025 with a 87%\nresponse rate. Overall satisfaction score was 4.2 out of 5.0. Work-life balance scored\n3.8/5.0. Career growth opportunities scored 3.9/5.0. Compensation satisfaction\nscored 3.6/5.0. The top requested improvement was 'more flexible remote work\noptions' cited by 62% of respondents. Employee retention rate for the trailing 12\nmonths was 91%.\n\n<!-- PageBreak -->\n\n\n## Contoso Partnership Announcements\n\nContoso announced three strategic partnerships in H1 2025: (1) A joint venture with\nMeridian Technologies for AI-powered document processing, valued at $5.2 million\nover 3 years. (2) A distribution agreement with Pacific Rim Solutions covering 12\ncountries in Asia-Pacific. (3) A technology integration partnership with NovaBridge\nSystems for unified identity management. The Chief Partnership Officer, Helena\nNakagawa, stated the partnerships are expected to generate an additional $15 million\nin revenue by 2027.\n",
+      "fields": {
+        "Summary": {
+          "type": "string",
+          "valueString": "The document provides a comprehensive overview of Contoso's key business metrics and initiatives for 2025, including financial performance for Q1 and Q2 with revenue, expenses, and profit details; a product roadmap with three major launches and R&D budget; employee satisfaction survey results highlighting scores and retention; and strategic partnership announcements expected to boost future revenue.",
+          "confidence": 0.46
+        }
+      },
+      "kind": "document",
+      "startPageNumber": 1,
+      "endPageNumber": 5,
+      "mimeType": "application/pdf",
+      "analyzerId": "prebuilt-documentSearch"
+    }
+  ]
+}

python/packages/azure-contentunderstanding/tests/cu/fixtures/analyze_video_result.json

@@ -0,0 +1,51 @@
+{
+  "id": "synthetic-video-001",
+  "status": "Succeeded",
+  "analyzer_id": "prebuilt-videoSearch",
+  "api_version": "2025-05-01-preview",
+  "created_at": "2026-03-21T10:15:00Z",
+  "contents": [
+    {
+      "kind": "audioVisual",
+      "startTimeMs": 1000,
+      "endTimeMs": 14000,
+      "width": 640,
+      "height": 480,
+      "markdown": "# Video: 00:01.000 => 00:14.000\n\nTranscript\n```\nWEBVTT\n\n00:01.000 --> 00:05.000\n<Speaker 1>Welcome to the Contoso Product Demo.\n\n00:05.000 --> 00:14.000\n<Speaker 1>Today we'll be showcasing our latest cloud infrastructure management tool.\n```",
+      "fields": {
+        "Summary": {
+          "type": "string",
+          "valueString": "Introduction to the Contoso Product Demo showcasing the latest cloud infrastructure management tool."
+        }
+      }
+    },
+    {
+      "kind": "audioVisual",
+      "startTimeMs": 15000,
+      "endTimeMs": 35000,
+      "width": 640,
+      "height": 480,
+      "markdown": "# Video: 00:15.000 => 00:35.000\n\nTranscript\n```\nWEBVTT\n\n00:15.000 --> 00:25.000\n<Speaker 1>As you can see on the dashboard, the system provides real-time monitoring of all deployed resources.\n\n00:25.000 --> 00:35.000\n<Speaker 1>Key features include automated scaling, cost optimization, and security compliance monitoring.\n```",
+      "fields": {
+        "Summary": {
+          "type": "string",
+          "valueString": "Dashboard walkthrough covering real-time monitoring, automated scaling, cost optimization, and security compliance."
+        }
+      }
+    },
+    {
+      "kind": "audioVisual",
+      "startTimeMs": 36000,
+      "endTimeMs": 42000,
+      "width": 640,
+      "height": 480,
+      "markdown": "# Video: 00:36.000 => 00:42.000\n\nTranscript\n```\nWEBVTT\n\n00:36.000 --> 00:42.000\n<Speaker 1>Visit contoso.com/cloud-manager to learn more and start your free trial.\n```",
+      "fields": {
+        "Summary": {
+          "type": "string",
+          "valueString": "Call to action directing viewers to contoso.com/cloud-manager for more information and a free trial."
+        }
+      }
+    }
+  ]
+}

python/packages/azure-contentunderstanding/tests/cu/test_integration.py

@@ -0,0 +1,312 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Integration tests for ContentUnderstandingContextProvider.
+
+These tests require a live Azure Content Understanding endpoint.
+Set AZURE_CONTENTUNDERSTANDING_ENDPOINT to enable them.
+
+To generate fixtures for unit tests, run these tests with --update-fixtures flag
+and the resulting JSON files will be written to tests/cu/fixtures/.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+skip_if_cu_integration_tests_disabled = pytest.mark.skipif(
+    not os.environ.get("AZURE_CONTENTUNDERSTANDING_ENDPOINT"),
+    reason="CU integration tests disabled (AZURE_CONTENTUNDERSTANDING_ENDPOINT not set)",
+)
+
+FIXTURES_DIR = Path(__file__).parent / "fixtures"
+
+# Shared sample asset — same PDF used by samples and integration tests
+INVOICE_PDF_PATH = Path(__file__).resolve().parents[2] / "samples" / "shared" / "sample_assets" / "invoice.pdf"
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_cu_integration_tests_disabled
+async def test_analyze_pdf_binary() -> None:
+    """Analyze a PDF via binary upload and optionally capture fixture."""
+    from azure.ai.contentunderstanding.aio import ContentUnderstandingClient
+    from azure.identity.aio import DefaultAzureCredential
+
+    endpoint = os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"]
+    analyzer_id = os.environ.get("AZURE_CONTENTUNDERSTANDING_ANALYZER_ID", "prebuilt-documentSearch")
+
+    pdf_path = INVOICE_PDF_PATH
+    assert pdf_path.exists(), f"Test fixture not found: {pdf_path}"
+    pdf_bytes = pdf_path.read_bytes()
+
+    async with DefaultAzureCredential() as credential, ContentUnderstandingClient(endpoint, credential) as client:
+        poller = await client.begin_analyze_binary(
+            analyzer_id,
+            binary_input=pdf_bytes,
+            content_type="application/pdf",
+        )
+        result = await poller.result()
+
+    assert result.contents
+    assert result.contents[0].markdown
+    assert len(result.contents[0].markdown) > 10
+    assert "CONTOSO LTD." in result.contents[0].markdown
+
+    # Optionally capture fixture
+    if os.environ.get("CU_UPDATE_FIXTURES"):
+        FIXTURES_DIR.mkdir(exist_ok=True)
+        fixture_path = FIXTURES_DIR / "analyze_pdf_result.json"
+        fixture_path.write_text(json.dumps(result.as_dict(), indent=2, default=str))
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_cu_integration_tests_disabled
+async def test_before_run_e2e() -> None:
+    """End-to-end test: Content.from_data → before_run → state populated."""
+    from agent_framework import Content, Message, SessionContext
+    from agent_framework._sessions import AgentSession
+    from azure.identity.aio import DefaultAzureCredential
+
+    from agent_framework_azure_contentunderstanding import ContentUnderstandingContextProvider
+
+    endpoint = os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"]
+
+    pdf_path = INVOICE_PDF_PATH
+    assert pdf_path.exists(), f"Test fixture not found: {pdf_path}"
+    pdf_bytes = pdf_path.read_bytes()
+
+    async with DefaultAzureCredential() as credential:
+        cu = ContentUnderstandingContextProvider(
+            endpoint=endpoint,
+            credential=credential,
+            max_wait=None,  # wait until analysis completes (no background deferral)
+        )
+        async with cu:
+            msg = Message(
+                role="user",
+                contents=[
+                    Content.from_text("What's in this document?"),
+                    Content.from_data(
+                        pdf_bytes,
+                        "application/pdf",
+                        additional_properties={"filename": "invoice.pdf"},
+                    ),
+                ],
+            )
+            context = SessionContext(input_messages=[msg])
+            state: dict[str, object] = {}
+            session = AgentSession()
+
+            from unittest.mock import MagicMock
+
+            await cu.before_run(agent=MagicMock(), session=session, context=context, state=state)
+
+            docs = state.get("documents", {})
+            assert isinstance(docs, dict)
+            assert "invoice.pdf" in docs
+            doc_entry = docs["invoice.pdf"]
+            assert doc_entry["status"] == "ready"
+            assert doc_entry["result"] is not None
+            assert doc_entry["result"].get("markdown")
+            assert len(doc_entry["result"]["markdown"]) > 10
+            assert "CONTOSO LTD." in doc_entry["result"]["markdown"]
+
+
+# Raw GitHub URL for a public invoice PDF from the CU samples repo
+_INVOICE_PDF_URL = (
+    "https://raw.githubusercontent.com/Azure-Samples/azure-ai-content-understanding-assets/main/document/invoice.pdf"
+)
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_cu_integration_tests_disabled
+async def test_before_run_uri_content() -> None:
+    """End-to-end test: Content.from_uri with an external URL → before_run → state populated.
+
+    Verifies that CU can analyze a file referenced by URL (not base64 data).
+    Uses a public invoice PDF from the Azure CU samples repository.
+    """
+    from agent_framework import Content, Message, SessionContext
+    from agent_framework._sessions import AgentSession
+    from azure.identity.aio import DefaultAzureCredential
+
+    from agent_framework_azure_contentunderstanding import ContentUnderstandingContextProvider
+
+    endpoint = os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"]
+
+    async with DefaultAzureCredential() as credential:
+        cu = ContentUnderstandingContextProvider(
+            endpoint=endpoint,
+            credential=credential,
+            max_wait=None,  # wait until analysis completes (no background deferral)
+        )
+        async with cu:
+            msg = Message(
+                role="user",
+                contents=[
+                    Content.from_text("What's on this invoice?"),
+                    Content.from_uri(
+                        uri=_INVOICE_PDF_URL,
+                        media_type="application/pdf",
+                        additional_properties={"filename": "invoice.pdf"},
+                    ),
+                ],
+            )
+            context = SessionContext(input_messages=[msg])
+            state: dict[str, object] = {}
+            session = AgentSession()
+
+            from unittest.mock import MagicMock
+
+            await cu.before_run(agent=MagicMock(), session=session, context=context, state=state)
+
+            docs = state.get("documents", {})
+            assert isinstance(docs, dict)
+            assert "invoice.pdf" in docs
+
+            doc_entry = docs["invoice.pdf"]
+            assert doc_entry["status"] == "ready"
+            assert doc_entry["result"] is not None
+            assert doc_entry["result"].get("markdown")
+            assert len(doc_entry["result"]["markdown"]) > 10
+            assert "CONTOSO LTD." in doc_entry["result"]["markdown"]
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_cu_integration_tests_disabled
+async def test_before_run_data_uri_content() -> None:
+    """End-to-end test: Content.from_uri with a base64 data URI → before_run → state populated.
+
+    Verifies that CU can analyze a file embedded as a data URI (data:application/pdf;base64,...).
+    This tests the data URI path: from_uri with "data:" prefix → type="data" → begin_analyze_binary.
+    """
+    import base64
+
+    from agent_framework import Content, Message, SessionContext
+    from agent_framework._sessions import AgentSession
+    from azure.identity.aio import DefaultAzureCredential
+
+    from agent_framework_azure_contentunderstanding import ContentUnderstandingContextProvider
+
+    endpoint = os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"]
+
+    pdf_path = INVOICE_PDF_PATH
+    assert pdf_path.exists(), f"Test fixture not found: {pdf_path}"
+    pdf_bytes = pdf_path.read_bytes()
+    b64 = base64.b64encode(pdf_bytes).decode("ascii")
+    data_uri = f"data:application/pdf;base64,{b64}"
+
+    async with DefaultAzureCredential() as credential:
+        cu = ContentUnderstandingContextProvider(
+            endpoint=endpoint,
+            credential=credential,
+            max_wait=None,  # wait until analysis completes
+        )
+        async with cu:
+            msg = Message(
+                role="user",
+                contents=[
+                    Content.from_text("What's on this invoice?"),
+                    Content.from_uri(
+                        uri=data_uri,
+                        media_type="application/pdf",
+                        additional_properties={"filename": "invoice_b64.pdf"},
+                    ),
+                ],
+            )
+            context = SessionContext(input_messages=[msg])
+            state: dict[str, object] = {}
+            session = AgentSession()
+
+            from unittest.mock import MagicMock
+
+            await cu.before_run(agent=MagicMock(), session=session, context=context, state=state)
+
+            docs = state.get("documents", {})
+            assert isinstance(docs, dict)
+            assert "invoice_b64.pdf" in docs
+
+            doc_entry = docs["invoice_b64.pdf"]
+            assert doc_entry["status"] == "ready"
+            assert doc_entry["result"] is not None
+            assert doc_entry["result"].get("markdown")
+            assert len(doc_entry["result"]["markdown"]) > 10
+            assert "CONTOSO LTD." in doc_entry["result"]["markdown"]
+
+
+@pytest.mark.flaky
+@pytest.mark.integration
+@skip_if_cu_integration_tests_disabled
+async def test_before_run_background_analysis() -> None:
+    """End-to-end test: max_wait timeout → background analysis → resolved on next turn.
+
+    Uses a short max_wait (0.5s) so CU analysis is deferred to background.
+    Then waits for analysis to complete and calls before_run again to verify
+    the background task resolves and the document becomes ready.
+    """
+    import asyncio
+
+    from agent_framework import Content, Message, SessionContext
+    from agent_framework._sessions import AgentSession
+    from azure.identity.aio import DefaultAzureCredential
+
+    from agent_framework_azure_contentunderstanding import ContentUnderstandingContextProvider
+
+    endpoint = os.environ["AZURE_CONTENTUNDERSTANDING_ENDPOINT"]
+
+    async with DefaultAzureCredential() as credential:
+        cu = ContentUnderstandingContextProvider(
+            endpoint=endpoint,
+            credential=credential,
+            max_wait=0.5,  # short timeout to force background deferral
+        )
+        async with cu:
+            # Turn 1: upload file — should time out and defer to background
+            msg = Message(
+                role="user",
+                contents=[
+                    Content.from_text("What's on this invoice?"),
+                    Content.from_uri(
+                        uri=_INVOICE_PDF_URL,
+                        media_type="application/pdf",
+                        additional_properties={"filename": "invoice.pdf"},
+                    ),
+                ],
+            )
+            context = SessionContext(input_messages=[msg])
+            state: dict[str, object] = {}
+            session = AgentSession()
+
+            from unittest.mock import MagicMock
+
+            await cu.before_run(agent=MagicMock(), session=session, context=context, state=state)
+
+            docs = state.get("documents", {})
+            assert isinstance(docs, dict)
+            assert "invoice.pdf" in docs
+            assert docs["invoice.pdf"]["status"] == "analyzing", (
+                f"Expected 'analyzing' but got '{docs['invoice.pdf']['status']}' — "
+                "CU responded too fast for the 0.5s timeout"
+            )
+            assert docs["invoice.pdf"]["result"] is None
+
+            # Wait for background analysis to complete
+            await asyncio.sleep(30)
+
+            # Turn 2: no new files — should resolve the background task
+            msg2 = Message(role="user", contents=[Content.from_text("Is it ready?")])
+            context2 = SessionContext(input_messages=[msg2])
+
+            await cu.before_run(agent=MagicMock(), session=session, context=context2, state=state)
+
+            assert docs["invoice.pdf"]["status"] == "ready"
+            assert docs["invoice.pdf"]["result"] is not None
+            assert docs["invoice.pdf"]["result"].get("markdown")
+            assert "CONTOSO LTD." in docs["invoice.pdf"]["result"]["markdown"]

python/packages/azure-contentunderstanding/tests/cu/test_models.py

@@ -0,0 +1,67 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+from agent_framework_azure_contentunderstanding._models import (
+    DocumentEntry,
+    DocumentStatus,
+    FileSearchConfig,
+)
+
+
+class TestDocumentEntry:
+    def test_construction(self) -> None:
+        entry: DocumentEntry = {
+            "status": DocumentStatus.READY,
+            "filename": "invoice.pdf",
+            "media_type": "application/pdf",
+            "analyzer_id": "prebuilt-documentSearch",
+            "analyzed_at": "2026-01-01T00:00:00+00:00",
+            "analysis_duration_s": 1.23,
+            "upload_duration_s": None,
+            "result": {"markdown": "# Title"},
+            "error": None,
+        }
+        assert entry["status"] == DocumentStatus.READY
+        assert entry["filename"] == "invoice.pdf"
+        assert entry["analyzer_id"] == "prebuilt-documentSearch"
+        assert entry["analysis_duration_s"] == 1.23
+        assert entry["upload_duration_s"] is None
+
+    def test_failed_entry(self) -> None:
+        entry: DocumentEntry = {
+            "status": DocumentStatus.FAILED,
+            "filename": "bad.pdf",
+            "media_type": "application/pdf",
+            "analyzer_id": "prebuilt-documentSearch",
+            "analyzed_at": "2026-01-01T00:00:00+00:00",
+            "analysis_duration_s": 0.5,
+            "upload_duration_s": None,
+            "result": None,
+            "error": "Service unavailable",
+        }
+        assert entry["status"] == DocumentStatus.FAILED
+        assert entry["error"] == "Service unavailable"
+        assert entry["result"] is None
+
+
+class TestFileSearchConfig:
+    def test_required_fields(self) -> None:
+        backend = AsyncMock()
+        tool = {"type": "file_search", "vector_store_ids": ["vs_123"]}
+        config = FileSearchConfig(backend=backend, vector_store_id="vs_123", file_search_tool=tool)
+        assert config.backend is backend
+        assert config.vector_store_id == "vs_123"
+        assert config.file_search_tool is tool
+
+    def test_from_openai_factory(self) -> None:
+        from agent_framework_azure_contentunderstanding._file_search import OpenAIFileSearchBackend
+
+        client = AsyncMock()
+        tool = {"type": "file_search", "vector_store_ids": ["vs_abc"]}
+        config = FileSearchConfig.from_openai(client, vector_store_id="vs_abc", file_search_tool=tool)
+        assert isinstance(config.backend, OpenAIFileSearchBackend)
+        assert config.vector_store_id == "vs_abc"
+        assert config.file_search_tool is tool

python/packages/azure-cosmos/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Cosmos DB history provider integration for Microsoft Agent
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260428"
+version = "1.0.0b260429"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "azure-cosmos>=4.3.0,<5",
 ]
 

python/packages/azurefunctions/pyproject.toml

@@ -4,7 +4,7 @@ description = "Azure Functions integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260428"
+version = "1.0.0b260429"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "agent-framework-durabletask",
     "azure-functions>=1.24.0,<2",
     "azure-functions-durable>=1.3.1,<2",

python/packages/bedrock/agent_framework_bedrock/_chat_client.py

@@ -405,6 +405,8 @@ class BedrockChatClient(
 
         tool_config = self._prepare_tools(options.get("tools"))
         if tool_mode := validate_tool_mode(options.get("tool_choice")):
+            if "allowed_tools" in tool_mode:
+                logger.warning("allowed_tools is not supported by Bedrock; the setting will be ignored")
             match tool_mode.get("mode"):
                 case "none":
                     # Bedrock doesn't support toolChoice "none".

python/packages/bedrock/pyproject.toml

@@ -4,7 +4,7 @@ description = "Amazon Bedrock integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260428"
+version = "1.0.0b260429"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "boto3>=1.35.0,<2.0.0",
     "botocore>=1.35.0,<2.0.0",
 ]

python/packages/chatkit/pyproject.toml

@@ -4,7 +4,7 @@ description = "OpenAI ChatKit integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260428"
+version = "1.0.0b260429"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "openai-chatkit>=1.4.1,<2.0.0",
 ]
 

python/packages/claude/pyproject.toml

@@ -4,7 +4,7 @@ description = "Claude Agent SDK integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260428"
+version = "1.0.0b260429"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "claude-agent-sdk>=0.1.36,<0.1.49",
 ]
 

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.0b260428"
+version = "1.0.0b260429"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "microsoft-agents-copilotstudio-client>=0.3.1,<0.3.2",
 ]
 

python/packages/core/agent_framework/_types.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import base64
+import contextlib
 import json
 import logging
 import re
@@ -2890,6 +2891,7 @@ class ResponseStream(AsyncIterable[UpdateT], Generic[UpdateT, FinalT]):
         self._inner_stream_source: ResponseStream[Any, Any] | Awaitable[ResponseStream[Any, Any]] | None = None
         self._wrap_inner: bool = False
         self._map_update: Callable[[Any], UpdateT | Awaitable[UpdateT]] | None = None
+        self._pull_context_manager_factories: list[Callable[[], contextlib.AbstractContextManager[Any]]] = []
 
     def map(
         self,
@@ -3008,11 +3010,18 @@ class ResponseStream(AsyncIterable[UpdateT], Generic[UpdateT, FinalT]):
         return self
 
     async def __anext__(self) -> UpdateT:
-        if self._iterator is None:
-            stream = await self._get_stream()
-            self._iterator = stream.__aiter__()
         try:
-            update: UpdateT = await self._iterator.__anext__()
+            with contextlib.ExitStack() as stack:
+                for factory in self._pull_context_manager_factories:
+                    stack.enter_context(factory())
+                # Resolve the underlying stream inside the pull contexts so that any
+                # spans/contexts created during stream resolution (e.g. inner chat
+                # completion spans created on the first pull of a wrapped agent stream)
+                # inherit the active context (e.g. an outer agent invoke span).
+                if self._iterator is None:
+                    stream = await self._get_stream()
+                    self._iterator = stream.__aiter__()
+                update: UpdateT = await self._iterator.__anext__()
         except StopAsyncIteration:
             self._consumed = True
             await self._run_cleanup_hooks()
@@ -3038,9 +3047,25 @@ class ResponseStream(AsyncIterable[UpdateT], Generic[UpdateT, FinalT]):
                 update = hooked
         return update
 
+    async def _resolve_stream_with_pull_contexts(self) -> AsyncIterable[UpdateT]:
+        """Resolve the underlying stream while activating any registered pull context managers.
+
+        Used by ``__await__`` and ``get_final_response`` so that any spans/contexts created
+        during stream resolution (e.g. when the source is an Awaitable that internally
+        creates child telemetry spans) inherit the same active context as iterator pulls.
+        ``__anext__`` resolves the stream inside its own ExitStack and so calls ``_get_stream``
+        directly.
+        """
+        if self._stream is not None:
+            return await self._get_stream()
+        with contextlib.ExitStack() as stack:
+            for factory in self._pull_context_manager_factories:
+                stack.enter_context(factory())
+            return await self._get_stream()
+
     def __await__(self) -> Any:
         async def _wrap() -> ResponseStream[UpdateT, FinalT]:
-            await self._get_stream()
+            await self._resolve_stream_with_pull_contexts()
             return self
 
         return _wrap().__await__()
@@ -3064,10 +3089,12 @@ class ResponseStream(AsyncIterable[UpdateT], Generic[UpdateT, FinalT]):
         """
         if self._wrap_inner:
             if self._inner_stream is None:
-                # Use _get_stream() to resolve the awaitable - this properly handles
+                # Use _resolve_stream_with_pull_contexts() so that any spans/contexts
+                # created while resolving the awaitable (e.g. inner telemetry spans)
+                # inherit the same active context as iterator pulls. This also handles
                 # the case where _stream_source and _inner_stream_source are the same
                 # coroutine (e.g., from from_awaitable), avoiding double-await errors.
-                await self._get_stream()
+                await self._resolve_stream_with_pull_contexts()
             if self._inner_stream is None:
                 raise RuntimeError("Inner stream not available")
             if not self._finalized and not self._consumed:
@@ -3177,6 +3204,25 @@ class ResponseStream(AsyncIterable[UpdateT], Generic[UpdateT, FinalT]):
         self._cleanup_hooks.append(hook)
         return self
 
+    def with_pull_context_manager(
+        self,
+        cm_factory: Callable[[], contextlib.AbstractContextManager[Any]],
+    ) -> ResponseStream[UpdateT, FinalT]:
+        """Register a context manager factory invoked around each underlying iterator pull.
+
+        The factory is called once per ``__anext__`` and the returned context manager wraps
+        the await of the underlying iterator. This is useful for state that needs to be
+        active while the inner async work runs - for example, attaching an OpenTelemetry
+        span to the current context so child spans created by inner code (HTTP clients,
+        tool execution) are correctly parented.
+
+        Because the context manager is entered and exited within the same ``__anext__``
+        invocation, attach/detach style operations remain symmetric in the same async
+        context regardless of where the stream is iterated.
+        """
+        self._pull_context_manager_factories.append(cm_factory)
+        return self
+
     async def _run_cleanup_hooks(self) -> None:
         if self._cleanup_run:
             return
@@ -3200,10 +3246,12 @@ class ToolMode(TypedDict, total=False):
     Fields:
         mode: One of "auto", "required", or "none".
         required_function_name: Optional function name when `mode == "required"`.
+        allowed_tools: Optional list of tool names when `mode` is `"auto"` or `"required"`.
     """
 
     mode: Literal["auto", "required", "none"]
     required_function_name: str
+    allowed_tools: list[str]
 
 
 # region TypedDict-based Chat Options
@@ -3436,7 +3484,7 @@ def validate_tool_mode(
 
     Returns:
         A ToolMode dict (contains keys: "mode", and optionally
-        "required_function_name"), or ``None`` when not provided.
+        "required_function_name" or "allowed_tools"), or ``None`` when not provided.
 
     Raises:
         ContentError: If the tool_choice string is invalid.
@@ -3453,6 +3501,17 @@ def validate_tool_mode(
         raise ContentError(f"Invalid tool choice: {tool_choice['mode']}")
     if tool_choice["mode"] != "required" and "required_function_name" in tool_choice:
         raise ContentError("tool_choice with mode other than 'required' cannot have 'required_function_name'")
+    if tool_choice["mode"] not in ("auto", "required") and "allowed_tools" in tool_choice:
+        raise ContentError("tool_choice 'allowed_tools' is only valid when mode is 'auto' or 'required'")
+    if "allowed_tools" in tool_choice:
+        allowed_tools = tool_choice["allowed_tools"]
+        if isinstance(allowed_tools, str) or not isinstance(allowed_tools, Sequence):
+            raise ContentError("tool_choice 'allowed_tools' must be a non-string sequence of strings")
+        if not all(isinstance(tool_name, str) for tool_name in allowed_tools):
+            raise ContentError("tool_choice 'allowed_tools' must contain only strings")
+        normalized_tool_choice = dict(tool_choice)
+        normalized_tool_choice["allowed_tools"] = list(allowed_tools)
+        return cast(ToolMode, normalized_tool_choice)
     return tool_choice
 
 

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

@@ -437,6 +437,13 @@ class WorkflowAgent(BaseAgent):
                     yield event
 
         elif checkpoint_id is not None:
+            # Restore the prior workflow state from the checkpoint. Shared
+            # state (e.g. accumulated conversation history maintained by the
+            # workflow's executors) survives across turns because Workflow.run
+            # no longer wipes state per call. Callers who want to deliver a
+            # new user message after restore should make a second
+            # `workflow.run(message=...)` call - they are NOT mutually
+            # exclusive on the same instance, but each must be its own call.
             if streaming:
                 async for event in self.workflow.run(
                     stream=True,
@@ -528,6 +535,7 @@ class WorkflowAgent(BaseAgent):
                 raw_representations.append(output_event)
             else:
                 data = output_event.data
+
                 if isinstance(data, AgentResponseUpdate):
                     # We cannot support AgentResponseUpdate in non-streaming mode. This is because the message
                     # sequence cannot be guaranteed when there are streaming updates in between non-streaming
@@ -628,16 +636,23 @@ class WorkflowAgent(BaseAgent):
             A list of AgentResponseUpdate objects. Empty list if the event is not relevant.
         """
         if event.type == "output":
-            # Convert workflow output to agent response updates.
-            # Handle different data types appropriately.
             data = event.data
             executor_id = event.executor_id
 
             if isinstance(data, AgentResponseUpdate):
-                # Pass through AgentResponseUpdate directly (streaming from AgentExecutor)
-                if not data.author_name:
-                    data.author_name = executor_id
-                return [data]
+                # Construct a fresh AgentResponseUpdate so we don't mutate a payload
+                # that AgentExecutor still holds a reference to in its `updates` list.
+                return [
+                    AgentResponseUpdate(
+                        contents=list(data.contents),
+                        role=data.role,
+                        author_name=data.author_name or executor_id,
+                        response_id=data.response_id,
+                        message_id=data.message_id,
+                        created_at=data.created_at,
+                        raw_representation=data.raw_representation,
+                    )
+                ]
             if isinstance(data, AgentResponse):
                 # Convert each message in AgentResponse to an AgentResponseUpdate
                 updates: list[AgentResponseUpdate] = []

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

@@ -156,8 +156,9 @@ class AgentExecutor(Executor):
                    the agent run.
                 - "custom": use the provided context_filter function to determine which messages to include
                    as context for the agent run.
-            context_filter: An optional function for filtering conversation context when context_mode is set
-                to "custom".
+            context_filter: A function that takes the full conversation (list of Messages) as input and returns
+                a filtered list of Messages to be used as context for the agent run. This is required
+                if context_mode is set to "custom".
         """
         # Prefer provided id; else use agent.name if present; else generate deterministic prefix
         exec_id = id or resolve_agent_id(agent)

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

@@ -278,7 +278,12 @@ class Runner:
                     "Please rebuild the original workflow before resuming."
                 )
 
-            # Restore state
+            # Restore state. Clear first so import_state (which merges) does
+            # not leak stale keys from a prior run on this Workflow instance.
+            # This matters more now that Workflow.run() no longer wipes state
+            # per call - the only reset point for shared state on a reused
+            # instance is at restore time.
+            self._state.clear()
             self._state.import_state(checkpoint.state)
             # Restore executor states using the restored state
             await self._restore_executor_states()

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

@@ -299,7 +299,7 @@ class Workflow(DictConvertible):
     async def _run_workflow_with_tracing(
         self,
         initial_executor_fn: Callable[[], Awaitable[None]] | None = None,
-        reset_context: bool = True,
+        is_continuation: bool = False,
         streaming: bool = False,
         function_invocation_kwargs: Mapping[str, Mapping[str, Any]] | Mapping[str, Any] | None = None,
         client_kwargs: Mapping[str, Mapping[str, Any]] | Mapping[str, Any] | None = None,
@@ -310,13 +310,19 @@ class Workflow(DictConvertible):
         of external callers to maintain context across different workflow runs.
 
         Args:
-            initial_executor_fn: Optional function to execute initial executor
-            reset_context: Whether to reset the context for a new run
-            streaming: Whether to enable streaming mode for agents
+            initial_executor_fn: Optional function to execute initial executor.
+            is_continuation: True when this run is a continuation of prior
+                work (a checkpoint restore or a responses-only replay) rather
+                than a fresh new turn delivered via the start executor with
+                ``message=...``. Continuations preserve per-run accounting
+                (iteration counter and run kwargs) from the prior turn;
+                fresh-message runs reset them. Shared workflow state is
+                preserved in both cases.
+            streaming: Whether to enable streaming mode for agents.
             function_invocation_kwargs: Optional kwargs to store in State for function
-                invocations in subagents
+                invocations in subagents.
             client_kwargs: Optional kwargs to store in State for chat client
-                invocations in subagents
+                invocations in subagents.
 
         Yields:
             WorkflowEvent: The events generated during the workflow execution.
@@ -345,16 +351,26 @@ class Workflow(DictConvertible):
                     in_progress = WorkflowEvent.status(WorkflowRunState.IN_PROGRESS)
                 yield in_progress  # noqa: RUF070
 
-                # Reset context for a new run if supported
-                if reset_context:
+                # Per-run reset for fresh-message runs only. We deliberately
+                # do NOT clear shared workflow state (`_state.clear()`) or the
+                # runner context's in-flight messages (`reset_for_new_run()`)
+                # here - state and pending work persist across `run()` calls
+                # so that a `WorkflowAgent` can deliver multi-turn input on
+                # the same instance and have prior turns' context survive.
+                # Iteration counting and per-run kwargs ARE per-run though,
+                # so they're reset here.
+                if not is_continuation:
                     self._runner.reset_iteration_count()
-                    self._runner.context.reset_for_new_run()
-                    self._state.clear()
 
                 # Store run kwargs in State so executors can access them.
-                # Only overwrite when new kwargs are explicitly provided or state was
-                # just cleared (fresh run). On continuation (reset_context=False) with
-                # no new kwargs, preserve the kwargs from the original run.
+                # Per-run kwargs semantics:
+                # - On a fresh message run, prior kwargs go away (set to {}
+                #   by default, or to the new kwargs if provided). This
+                #   prevents stale kwargs from a prior turn leaking into the
+                #   current turn.
+                # - On a continuation (checkpoint restore or responses), the
+                #   prior run's kwargs are preserved unless the caller
+                #   explicitly provides new kwargs.
                 if function_invocation_kwargs is not None or client_kwargs is not None:
                     combined_kwargs: dict[str, Any] = {}
                     if function_invocation_kwargs is not None:
@@ -366,11 +382,12 @@ class Workflow(DictConvertible):
                             client_kwargs, "client_kwargs"
                         )
                     self._state.set(WORKFLOW_RUN_KWARGS_KEY, combined_kwargs)
-                elif reset_context:
+                elif not is_continuation:
                     self._state.set(WORKFLOW_RUN_KWARGS_KEY, {})
                 self._state.commit()  # Commit immediately so kwargs are available
 
-                # Set streaming mode after reset
+                # Set streaming mode (always set explicitly per run since
+                # reset_for_new_run() no longer runs to clear it).
                 self._runner_context.set_streaming(streaming)
 
                 # Execute initial setup if provided
@@ -585,13 +602,31 @@ class Workflow(DictConvertible):
         if checkpoint_storage is not None:
             self._runner.context.set_runtime_checkpoint_storage(checkpoint_storage)
 
-        initial_executor_fn, reset_context = self._resolve_execution_mode(
-            message, responses, checkpoint_id, checkpoint_storage
-        )
+        # Async validation: a fresh-message run is only allowed when the
+        # runner context has fully drained from any prior run. If it still
+        # has in-flight executor messages, the prior run didn't complete -
+        # the caller must either resume from a checkpoint or wait for the
+        # prior run to drain. (Pending request_info events are intentionally
+        # NOT blocked here: a follow-up run with message=... is the normal
+        # way to deliver a response to those pending requests, e.g. via
+        # WorkflowAgent._process_pending_requests.)
+        # NOTE: _validate_run_params already enforces that ``message`` is
+        # mutually exclusive with both ``checkpoint_id`` and ``responses``,
+        # so we don't need to re-check those here.
+        if message is not None and await self._runner.context.has_messages():
+            raise RuntimeError(
+                "Cannot start a new run with 'message' while in-flight executor "
+                "messages remain from a prior run. Resume from a checkpoint "
+                "(checkpoint_id=...) or wait for the prior run to complete. "
+                "Workflows that need to recover from a mid-run failure must use "
+                "checkpointing; there is no in-process recovery path."
+            )
+
+        initial_executor_fn = self._resolve_execution_mode(message, responses, checkpoint_id, checkpoint_storage)
 
         async for event in self._run_workflow_with_tracing(
             initial_executor_fn=initial_executor_fn,
-            reset_context=reset_context,
+            is_continuation=(message is None),
             streaming=streaming,
             function_invocation_kwargs=function_invocation_kwargs,
             client_kwargs=client_kwargs,
@@ -674,12 +709,8 @@ class Workflow(DictConvertible):
         responses: Mapping[str, Any] | None,
         checkpoint_id: str | None,
         checkpoint_storage: CheckpointStorage | None,
-    ) -> tuple[Callable[[], Awaitable[None]], bool]:
-        """Determine the initial executor function and reset_context flag based on parameters.
-
-        Returns:
-            A tuple of (initial_executor_fn, reset_context).
-        """
+    ) -> Callable[[], Awaitable[None]]:
+        """Determine the initial executor function based on parameters."""
         if responses is not None:
             if checkpoint_id is not None:
                 # Combined: restore checkpoint then send responses
@@ -689,13 +720,9 @@ class Workflow(DictConvertible):
             else:
                 # Send responses only (requires pending requests in workflow state)
                 initial_executor_fn = functools.partial(self._send_responses_internal, responses)
-            return initial_executor_fn, False
+            return initial_executor_fn
         # Regular run or checkpoint restoration
-        initial_executor_fn = functools.partial(
-            self._execute_with_message_or_checkpoint, message, checkpoint_id, checkpoint_storage
-        )
-        reset_context = message is not None and checkpoint_id is None
-        return initial_executor_fn, reset_context
+        return functools.partial(self._execute_with_message_or_checkpoint, message, checkpoint_id, checkpoint_storage)
 
     async def _restore_and_send_responses(
         self,

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

@@ -361,7 +361,7 @@ class WorkflowExecutor(Executor):
         return any(is_instance_of(message.data, input_type) for input_type in self.workflow.input_types)
 
     @handler
-    async def process_workflow(self, input_data: object, ctx: WorkflowContext[Any]) -> None:
+    async def process_workflow(self, input_data: object, ctx: WorkflowContext[Any, Any]) -> None:
         """Execute the sub-workflow with raw input data.
 
         This handler starts a new sub-workflow execution. When the sub-workflow
@@ -428,7 +428,7 @@ class WorkflowExecutor(Executor):
     async def handle_message_wrapped_request_response(
         self,
         response: SubWorkflowResponseMessage,
-        ctx: WorkflowContext[Any],
+        ctx: WorkflowContext[Any, Any],
     ) -> None:
         """Handle response from parent for a forwarded request.
 

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

@@ -21,10 +21,15 @@ _IMPORTS = [
     "AgentFactory",
     "AgentExternalInputRequest",
     "AgentExternalInputResponse",
+    "DeclarativeActionError",
     "DeclarativeLoaderError",
     "DeclarativeWorkflowError",
+    "DefaultHttpRequestHandler",
     "ExternalInputRequest",
     "ExternalInputResponse",
+    "HttpRequestHandler",
+    "HttpRequestInfo",
+    "HttpRequestResult",
     "ProviderLookupError",
     "ProviderTypeMapping",
     "WorkflowFactory",

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

@@ -4,10 +4,15 @@ from agent_framework_declarative import (
     AgentExternalInputRequest,
     AgentExternalInputResponse,
     AgentFactory,
+    DeclarativeActionError,
     DeclarativeLoaderError,
     DeclarativeWorkflowError,
+    DefaultHttpRequestHandler,
     ExternalInputRequest,
     ExternalInputResponse,
+    HttpRequestHandler,
+    HttpRequestInfo,
+    HttpRequestResult,
     ProviderLookupError,
     ProviderTypeMapping,
     WorkflowFactory,
@@ -18,10 +23,15 @@ __all__ = [
     "AgentExternalInputRequest",
     "AgentExternalInputResponse",
     "AgentFactory",
+    "DeclarativeActionError",
     "DeclarativeLoaderError",
     "DeclarativeWorkflowError",
+    "DefaultHttpRequestHandler",
     "ExternalInputRequest",
     "ExternalInputResponse",
+    "HttpRequestHandler",
+    "HttpRequestInfo",
+    "HttpRequestResult",
     "ProviderLookupError",
     "ProviderTypeMapping",
     "WorkflowFactory",

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

@@ -4,6 +4,7 @@
 
 This module lazily re-exports objects from:
 - ``agent-framework-anthropic``
+- ``agent-framework-azure-contentunderstanding``
 - ``agent-framework-foundry``
 - ``agent-framework-foundry-local``
 """
@@ -12,7 +13,15 @@ import importlib
 from typing import Any
 
 _IMPORTS: dict[str, tuple[str, str]] = {
+    "AnalysisSection": ("agent_framework_azure_contentunderstanding", "agent-framework-azure-contentunderstanding"),
     "AnthropicFoundryClient": ("agent_framework_anthropic", "agent-framework-anthropic"),
+    "ContentUnderstandingContextProvider": (
+        "agent_framework_azure_contentunderstanding",
+        "agent-framework-azure-contentunderstanding",
+    ),
+    "DocumentStatus": ("agent_framework_azure_contentunderstanding", "agent-framework-azure-contentunderstanding"),
+    "FileSearchBackend": ("agent_framework_azure_contentunderstanding", "agent-framework-azure-contentunderstanding"),
+    "FileSearchConfig": ("agent_framework_azure_contentunderstanding", "agent-framework-azure-contentunderstanding"),
     "FoundryAgent": ("agent_framework_foundry", "agent-framework-foundry"),
     "FoundryAgentOptions": ("agent_framework_foundry", "agent-framework-foundry"),
     "FoundryChatClient": ("agent_framework_foundry", "agent-framework-foundry"),

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

@@ -4,6 +4,13 @@
 # Install the relevant packages for full type support.
 
 from agent_framework_anthropic import AnthropicFoundryClient, RawAnthropicFoundryClient
+from agent_framework_azure_contentunderstanding import (  # pyright: ignore[reportMissingImports]
+    AnalysisSection,  # pyright: ignore[reportUnknownVariableType]
+    ContentUnderstandingContextProvider,  # pyright: ignore[reportUnknownVariableType]
+    DocumentStatus,  # pyright: ignore[reportUnknownVariableType]
+    FileSearchBackend,  # pyright: ignore[reportUnknownVariableType]
+    FileSearchConfig,  # pyright: ignore[reportUnknownVariableType]
+)
 from agent_framework_foundry import (
     FoundryAgent,
     FoundryChatClient,
@@ -31,7 +38,12 @@ from agent_framework_foundry_local import (
 )
 
 __all__ = [
+    "AnalysisSection",
     "AnthropicFoundryClient",
+    "ContentUnderstandingContextProvider",
+    "DocumentStatus",
+    "FileSearchBackend",
+    "FileSearchConfig",
     "FoundryAgent",
     "FoundryChatClient",
     "FoundryChatOptions",

python/packages/core/agent_framework/observability.py

@@ -26,6 +26,7 @@ from time import perf_counter, time_ns
 from typing import TYPE_CHECKING, Any, ClassVar, Final, Generic, Literal, TypedDict, cast, overload
 
 from dotenv import load_dotenv
+from opentelemetry import context as otel_context
 from opentelemetry import metrics, trace
 
 from . import __version__ as version_info
@@ -1277,27 +1278,8 @@ class ChatTelemetryLayer(Generic[OptionsCoT]):
         )
 
         if stream:
-            result_stream = cast(
-                ResponseStream[ChatResponseUpdate, ChatResponse[Any]],
-                super_get_response(
-                    messages=messages,
-                    stream=True,
-                    options=opts,
-                    compaction_strategy=compaction_strategy,
-                    tokenizer=tokenizer,
-                    function_invocation_kwargs=function_invocation_kwargs,
-                    client_kwargs=merged_client_kwargs,
-                ),
-            )
+            span = _start_streaming_span(attributes, OtelAttr.REQUEST_MODEL)
 
-            # Create span directly without trace.use_span() context attachment.
-            # Streaming spans are closed asynchronously in cleanup hooks, which run
-            # in a different async context than creation — using use_span() would
-            # cause "Failed to detach context" errors from OpenTelemetry.
-            operation = attributes.get(OtelAttr.OPERATION, "operation")
-            span_name = attributes.get(OtelAttr.REQUEST_MODEL, "unknown")
-            span = get_tracer().start_span(f"{operation} {span_name}")
-            span.set_attributes(attributes)
             if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED and messages:
                 _capture_messages(
                     span=span,
@@ -1319,6 +1301,24 @@ class ChatTelemetryLayer(Generic[OptionsCoT]):
             def _record_duration() -> None:
                 duration_state["duration"] = perf_counter() - start_time
 
+            try:
+                result_stream = cast(
+                    ResponseStream[ChatResponseUpdate, ChatResponse[Any]],
+                    super_get_response(
+                        messages=messages,
+                        stream=True,
+                        options=opts,
+                        compaction_strategy=compaction_strategy,
+                        tokenizer=tokenizer,
+                        function_invocation_kwargs=function_invocation_kwargs,
+                        client_kwargs=merged_client_kwargs,
+                    ),
+                )
+            except Exception as exception:
+                capture_exception(span=span, exception=exception, timestamp=time_ns())
+                _close_span()
+                raise
+
             async def _finalize_stream() -> None:
                 from ._types import ChatResponse
 
@@ -1357,11 +1357,18 @@ class ChatTelemetryLayer(Generic[OptionsCoT]):
                 finally:
                     _close_span()
 
-            # Register a weak reference callback to close the span if stream is garbage collected
-            # without being consumed. This ensures spans don't leak if users don't consume streams.
-            wrapped_stream: ResponseStream[ChatResponseUpdate, ChatResponse[Any]] = result_stream.with_cleanup_hook(
-                _record_duration
-            ).with_cleanup_hook(_finalize_stream)
+            # The pull context manager attaches the span around each underlying iterator pull so
+            # that child spans created during the pull (e.g. HTTP requests, inner tool execution)
+            # are parented under this chat span. Attach and detach happen in the same async
+            # context as the pull, avoiding cross-context cleanup issues. The weakref finalizer
+            # ensures the span is closed even if the stream is garbage collected without being
+            # consumed.
+            wrapped_stream: ResponseStream[ChatResponseUpdate, ChatResponse[Any]] = (
+                result_stream
+                .with_cleanup_hook(_record_duration)
+                .with_cleanup_hook(_finalize_stream)
+                .with_pull_context_manager(lambda: _activate_span(span))
+            )
             weakref.finalize(wrapped_stream, _close_span)
             return wrapped_stream
 
@@ -1543,23 +1550,8 @@ class AgentTelemetryLayer:
         inner_accumulated_usage_token = INNER_ACCUMULATED_USAGE.set({})
 
         if stream:
-            try:
-                run_result: object = execute()
-                if isinstance(run_result, ResponseStream):
-                    result_stream: ResponseStream[AgentResponseUpdate, AgentResponse[Any]] = run_result  # pyright: ignore[reportUnknownVariableType]
-                elif isinstance(run_result, Awaitable):
-                    result_stream = ResponseStream.from_awaitable(run_result)  # type: ignore[arg-type]  # pyright: ignore[reportArgumentType]
-                else:
-                    raise RuntimeError("Streaming telemetry requires a ResponseStream result.")
-            except Exception:
-                INNER_RESPONSE_TELEMETRY_CAPTURED_FIELDS.reset(inner_response_telemetry_captured_fields_token)
-                INNER_ACCUMULATED_USAGE.reset(inner_accumulated_usage_token)
-                raise
+            span = _start_streaming_span(attributes, OtelAttr.AGENT_NAME)
 
-            operation = attributes.get(OtelAttr.OPERATION, "operation")
-            span_name = attributes.get(OtelAttr.AGENT_NAME, "unknown")
-            span = get_tracer().start_span(f"{operation} {span_name}")
-            span.set_attributes(attributes)
             if OBSERVABILITY_SETTINGS.SENSITIVE_DATA_ENABLED and messages:
                 _capture_messages(
                     span=span,
@@ -1581,6 +1573,21 @@ class AgentTelemetryLayer:
             def _record_duration() -> None:
                 duration_state["duration"] = perf_counter() - start_time
 
+            try:
+                run_result: object = execute()
+                if isinstance(run_result, ResponseStream):
+                    result_stream: ResponseStream[AgentResponseUpdate, AgentResponse[Any]] = run_result  # pyright: ignore[reportUnknownVariableType]
+                elif isinstance(run_result, Awaitable):
+                    result_stream = ResponseStream.from_awaitable(run_result)  # type: ignore[arg-type]  # pyright: ignore[reportArgumentType]
+                else:
+                    raise RuntimeError("Streaming telemetry requires a ResponseStream result.")
+            except Exception as exception:
+                capture_exception(span=span, exception=exception, timestamp=time_ns())
+                INNER_RESPONSE_TELEMETRY_CAPTURED_FIELDS.reset(inner_response_telemetry_captured_fields_token)
+                INNER_ACCUMULATED_USAGE.reset(inner_accumulated_usage_token)
+                _close_span()
+                raise
+
             async def _finalize_stream() -> None:
                 from ._types import AgentResponse
 
@@ -1620,9 +1627,18 @@ class AgentTelemetryLayer:
                     INNER_ACCUMULATED_USAGE.reset(inner_accumulated_usage_token)
                     _close_span()
 
-            wrapped_stream: ResponseStream[AgentResponseUpdate, AgentResponse[Any]] = result_stream.with_cleanup_hook(
-                _record_duration
-            ).with_cleanup_hook(_finalize_stream)
+            # The pull context manager attaches the span around each underlying iterator pull so
+            # that child spans created during the pull (e.g. inner chat completion spans from the
+            # underlying ChatTelemetryLayer) are parented under this agent invoke span. Attach and
+            # detach happen in the same async context as the pull, avoiding cross-context cleanup
+            # issues. The weakref finalizer ensures the span is closed even if the stream is
+            # garbage collected without being consumed.
+            wrapped_stream: ResponseStream[AgentResponseUpdate, AgentResponse[Any]] = (
+                result_stream
+                .with_cleanup_hook(_record_duration)
+                .with_cleanup_hook(_finalize_stream)
+                .with_pull_context_manager(lambda: _activate_span(span))
+            )
             weakref.finalize(wrapped_stream, _close_span)
             return wrapped_stream
 
@@ -1809,6 +1825,27 @@ def get_function_span(
     )
 
 
+@contextlib.contextmanager
+def _activate_span(span: trace.Span) -> Generator[None]:
+    """Attach ``span`` as the current span in the OpenTelemetry context.
+
+    Designed to be used as a per-pull context manager registered on a
+    ``ResponseStream`` via ``with_pull_context_manager``: it attaches the span
+    before each underlying iterator pull and detaches immediately after, so
+    child spans created during the pull (HTTP clients, inner chat completions,
+    tool execution) are correctly parented under ``span``.
+
+    Because attach and detach happen within the same ``__anext__`` invocation
+    (and therefore the same async task / contextvars context), there is no risk
+    of "Failed to detach context" warnings from cross-context cleanup.
+    """
+    token = otel_context.attach(trace.set_span_in_context(span))
+    try:
+        yield
+    finally:
+        otel_context.detach(token)
+
+
 @contextlib.contextmanager
 def _get_span(
     attributes: dict[str, Any],
@@ -1831,6 +1868,29 @@ def _get_span(
         yield current_span
 
 
+def _start_streaming_span(attributes: dict[str, Any], span_name_attribute: str) -> trace.Span:
+    """Start a non-current span for a streaming operation.
+
+    Unlike :func:`_get_span`, the returned span is not attached to the current
+    OpenTelemetry context. The caller is responsible for:
+
+    - Ending the span via cleanup hooks on the wrapped
+      :class:`~agent_framework._types.ResponseStream`.
+    - Activating the span around each iterator pull via
+      :func:`_activate_span` registered with ``with_pull_context_manager`` so
+      that child spans created during stream production inherit it as parent.
+
+    Streaming spans are closed asynchronously in cleanup hooks that run in a
+    different async context than creation, so attaching the span at creation
+    time would cause "Failed to detach context" errors from OpenTelemetry.
+    """
+    operation = attributes.get(OtelAttr.OPERATION, "operation")
+    span_name = attributes.get(span_name_attribute, "unknown")
+    span = get_tracer().start_span(f"{operation} {span_name}")
+    span.set_attributes(attributes)
+    return span
+
+
 def _get_instructions_from_options(options: Any) -> str | list[str] | None:
     """Extract instructions from options dict."""
     if options is None:

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.2.1"
+version = "1.2.2"
 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/core/test_observability.py

@@ -3313,3 +3313,487 @@ async def test_agent_invoke_span_aggregates_usage_on_max_iterations_exhaustion(s
     # The invoke_agent span must aggregate usage from the in-loop call and the final exhaustion call
     assert agent_span.attributes.get(OtelAttr.INPUT_TOKENS) == 500
     assert agent_span.attributes.get(OtelAttr.OUTPUT_TOKENS) == 100
+
+
+# region Test span nesting (parent-child relationships)
+
+
+@pytest.mark.parametrize("stream", [False, True])
+async def test_chat_span_nested_under_agent_span(span_exporter: InMemorySpanExporter, stream: bool):
+    """The inner chat span must be a child of the outer agent invoke span."""
+
+    class NestedChatClient(ChatTelemetryLayer, BaseChatClient[Any]):
+        def service_url(self):
+            return "https://test.example.com"
+
+        def _inner_get_response(
+            self, *, messages: MutableSequence[Message], stream: bool, options: dict[str, Any], **kwargs: Any
+        ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]:
+            if stream:
+
+                async def _stream() -> AsyncIterable[ChatResponseUpdate]:
+                    yield ChatResponseUpdate(contents=[Content.from_text("Hello")], role="assistant")
+                    yield ChatResponseUpdate(
+                        contents=[Content.from_text(" world")], role="assistant", finish_reason="stop"
+                    )
+
+                def _finalize(updates: Sequence[ChatResponseUpdate]) -> ChatResponse:
+                    return ChatResponse(
+                        messages=[Message(role="assistant", contents=["Hello world"])],
+                        response_id="resp_1",
+                        usage_details=UsageDetails(input_token_count=3, output_token_count=4),
+                        finish_reason="stop",
+                    )
+
+                return ResponseStream(_stream(), finalizer=_finalize)
+
+            async def _get() -> ChatResponse:
+                return ChatResponse(
+                    messages=[Message(role="assistant", contents=["Hello world"])],
+                    response_id="resp_1",
+                    usage_details=UsageDetails(input_token_count=3, output_token_count=4),
+                    finish_reason="stop",
+                )
+
+            return _get()
+
+    agent = Agent(
+        client=NestedChatClient(),
+        id="nested_agent_id",
+        name="nested_agent",
+        default_options={"model": "NestedModel"},
+    )
+
+    span_exporter.clear()
+    if stream:
+        result_stream = agent.run("Test message", stream=True)
+        async for _ in result_stream:
+            pass
+        await result_stream.get_final_response()
+    else:
+        await agent.run("Test message")
+
+    spans = span_exporter.get_finished_spans()
+    assert len(spans) == 2
+
+    span_by_op = {s.attributes[OtelAttr.OPERATION.value]: s for s in spans}
+    agent_span = span_by_op[OtelAttr.AGENT_INVOKE_OPERATION]
+    chat_span = span_by_op[OtelAttr.CHAT_COMPLETION_OPERATION]
+
+    # Agent span has no parent (it is the root)
+    assert agent_span.parent is None
+
+    # Chat span's parent must be the agent span
+    assert chat_span.parent is not None
+    assert chat_span.parent.span_id == agent_span.context.span_id
+    assert chat_span.parent.trace_id == agent_span.context.trace_id
+
+    # Both spans must share the same trace
+    assert chat_span.context.trace_id == agent_span.context.trace_id
+
+
+@pytest.mark.parametrize("stream", [False, True])
+async def test_function_call_spans_nested_under_agent_span(span_exporter: InMemorySpanExporter, stream: bool):
+    """All inner spans (chat completions and execute_tool) must be children of the agent span."""
+    from agent_framework import Content
+    from agent_framework._tools import FunctionInvocationLayer
+
+    @tool(name="get_weather", description="Get the weather for a location")
+    def get_weather(location: str) -> str:
+        return f"The weather in {location} is sunny."
+
+    class NestedToolChatClient(FunctionInvocationLayer, ChatTelemetryLayer, BaseChatClient[Any]):
+        def __init__(self) -> None:
+            super().__init__()
+            self.call_count = 0
+
+        def service_url(self):
+            return "https://test.example.com"
+
+        def _inner_get_response(
+            self, *, messages: MutableSequence[Message], stream: bool, options: dict[str, Any], **kwargs: Any
+        ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]:
+            self.call_count += 1
+            is_first = self.call_count == 1
+
+            if stream:
+
+                async def _stream() -> AsyncIterable[ChatResponseUpdate]:
+                    if is_first:
+                        yield ChatResponseUpdate(
+                            contents=[
+                                Content.from_function_call(
+                                    call_id="call_123",
+                                    name="get_weather",
+                                    arguments='{"location": "Seattle"}',
+                                )
+                            ],
+                            role="assistant",
+                        )
+                    else:
+                        yield ChatResponseUpdate(
+                            contents=[Content.from_text("The weather in Seattle is sunny!")],
+                            role="assistant",
+                            finish_reason="stop",
+                        )
+
+                def _finalize(updates: Sequence[ChatResponseUpdate]) -> ChatResponse:
+                    return ChatResponse.from_updates(updates)
+
+                return ResponseStream(_stream(), finalizer=_finalize)
+
+            async def _get() -> ChatResponse:
+                if is_first:
+                    return ChatResponse(
+                        messages=[
+                            Message(
+                                role="assistant",
+                                contents=[
+                                    Content.from_function_call(
+                                        call_id="call_123",
+                                        name="get_weather",
+                                        arguments='{"location": "Seattle"}',
+                                    )
+                                ],
+                            )
+                        ],
+                    )
+                return ChatResponse(
+                    messages=[Message(role="assistant", contents=["The weather in Seattle is sunny!"])],
+                    finish_reason="stop",
+                )
+
+            return _get()
+
+    agent = Agent(
+        client=NestedToolChatClient(),
+        id="tool_agent_id",
+        name="tool_agent",
+        default_options={"model": "ToolModel", "tools": [get_weather], "tool_choice": "auto"},
+    )
+
+    span_exporter.clear()
+    if stream:
+        result_stream = agent.run("What's the weather in Seattle?", stream=True)
+        async for _ in result_stream:
+            pass
+        await result_stream.get_final_response()
+    else:
+        await agent.run("What's the weather in Seattle?")
+
+    spans = span_exporter.get_finished_spans()
+
+    invoke_spans = [s for s in spans if s.attributes.get(OtelAttr.OPERATION.value) == OtelAttr.AGENT_INVOKE_OPERATION]
+    chat_spans = [s for s in spans if s.attributes.get(OtelAttr.OPERATION.value) == OtelAttr.CHAT_COMPLETION_OPERATION]
+    tool_spans = [s for s in spans if s.attributes.get(OtelAttr.OPERATION.value) == OtelAttr.TOOL_EXECUTION_OPERATION]
+
+    assert len(invoke_spans) == 1, f"Expected 1 invoke_agent span, got {len(invoke_spans)}"
+    assert len(chat_spans) == 2, f"Expected 2 chat spans, got {len(chat_spans)}"
+    assert len(tool_spans) == 1, f"Expected 1 execute_tool span, got {len(tool_spans)}"
+
+    agent_span = invoke_spans[0]
+    assert agent_span.parent is None
+
+    # All inner spans must be parented under the agent invoke span
+    for inner in (*chat_spans, *tool_spans):
+        assert inner.parent is not None, f"Span {inner.name} has no parent"
+        assert inner.parent.span_id == agent_span.context.span_id, (
+            f"Span {inner.name} parent={inner.parent.span_id} != agent={agent_span.context.span_id}"
+        )
+        assert inner.context.trace_id == agent_span.context.trace_id
+
+
+@pytest.mark.parametrize("stream", [False, True])
+async def test_chat_span_nested_under_explicit_outer_span(
+    span_exporter: InMemorySpanExporter, mock_chat_client, stream: bool
+):
+    """Chat telemetry spans (including streaming) must inherit a user-provided outer span as parent."""
+    from agent_framework.observability import get_tracer
+
+    client = mock_chat_client()
+    span_exporter.clear()
+
+    tracer = get_tracer()
+    with tracer.start_as_current_span("outer") as outer_span:
+        outer_ctx = outer_span.get_span_context()
+        if stream:
+            stream_obj = client.get_response(
+                stream=True, messages=[Message(role="user", contents=["Test"])], options={"model": "Test"}
+            )
+            async for _ in stream_obj:
+                pass
+            await stream_obj.get_final_response()
+        else:
+            await client.get_response(messages=[Message(role="user", contents=["Test"])], options={"model": "Test"})
+
+    spans = span_exporter.get_finished_spans()
+    chat_spans = [s for s in spans if s.attributes.get(OtelAttr.OPERATION.value) == OtelAttr.CHAT_COMPLETION_OPERATION]
+    assert len(chat_spans) == 1
+    chat_span = chat_spans[0]
+
+    assert chat_span.parent is not None
+    assert chat_span.parent.span_id == outer_ctx.span_id
+    assert chat_span.context.trace_id == outer_ctx.trace_id
+
+
+@pytest.mark.parametrize("stream", [False, True])
+async def test_http_span_nested_under_chat_span(span_exporter: InMemorySpanExporter, stream: bool):
+    """A span created inside ``_inner_get_response`` (e.g. an HTTP client call to the LLM provider)
+    must be parented under the chat completion span.
+
+    This validates that the chat span context is active while the inner client implementation
+    runs, both for non-streaming responses and while streaming updates are being pulled.
+    """
+    from agent_framework.observability import get_tracer
+
+    tracer = get_tracer()
+
+    class HttpEmittingClient(ChatTelemetryLayer, BaseChatClient[Any]):
+        def service_url(self):
+            return "https://test.example.com"
+
+        def _inner_get_response(
+            self, *, messages: MutableSequence[Message], stream: bool, options: dict[str, Any], **kwargs: Any
+        ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]:
+            if stream:
+
+                async def _stream() -> AsyncIterable[ChatResponseUpdate]:
+                    # Simulate an HTTP request to the model provider while producing the stream.
+                    with tracer.start_as_current_span("HTTP POST"):
+                        pass
+                    yield ChatResponseUpdate(contents=[Content.from_text("hi")], role="assistant", finish_reason="stop")
+
+                def _finalize(updates: Sequence[ChatResponseUpdate]) -> ChatResponse:
+                    return ChatResponse.from_updates(updates)
+
+                return ResponseStream(_stream(), finalizer=_finalize)
+
+            async def _get() -> ChatResponse:
+                # Simulate an HTTP request to the model provider during the call.
+                with tracer.start_as_current_span("HTTP POST"):
+                    pass
+                return ChatResponse(
+                    messages=[Message(role="assistant", contents=["done"])],
+                    usage_details=UsageDetails(input_token_count=1, output_token_count=1),
+                )
+
+            return _get()
+
+    span_exporter.clear()
+    client = HttpEmittingClient()
+    if stream:
+        result_stream = client.get_response(
+            stream=True, messages=[Message(role="user", contents=["Test"])], options={"model": "Test"}
+        )
+        async for _ in result_stream:
+            pass
+        await result_stream.get_final_response()
+    else:
+        await client.get_response(messages=[Message(role="user", contents=["Test"])], options={"model": "Test"})
+
+    spans = span_exporter.get_finished_spans()
+    chat_spans = [s for s in spans if s.attributes.get(OtelAttr.OPERATION.value) == OtelAttr.CHAT_COMPLETION_OPERATION]
+    http_spans = [s for s in spans if s.name == "HTTP POST"]
+    assert len(chat_spans) == 1
+    assert len(http_spans) == 1
+
+    chat_span = chat_spans[0]
+    http_span = http_spans[0]
+
+    assert http_span.parent is not None
+    assert http_span.parent.span_id == chat_span.context.span_id
+    assert http_span.context.trace_id == chat_span.context.trace_id
+
+
+# region Test ResponseStream.with_pull_context_manager
+
+
+async def test_with_pull_context_manager_enters_and_exits_per_pull():
+    """The registered factory is entered and exited symmetrically around each iterator pull."""
+    import contextlib
+
+    events: list[str] = []
+
+    @contextlib.contextmanager
+    def cm():
+        events.append("enter")
+        try:
+            yield
+        finally:
+            events.append("exit")
+
+    async def src() -> AsyncIterable[int]:
+        yield 1
+        yield 2
+
+    stream: ResponseStream[int, list[int]] = ResponseStream(src(), finalizer=lambda updates: list(updates))
+    stream.with_pull_context_manager(cm)
+
+    pulled = [u async for u in stream]
+
+    assert pulled == [1, 2]
+    # Enter/exit must be balanced and there must be at least one pair per yielded update.
+    assert events.count("enter") == events.count("exit")
+    assert events.count("enter") >= 2
+    # Verify symmetric ordering (no overlapping pairs).
+    for i in range(0, len(events), 2):
+        assert events[i] == "enter"
+        assert events[i + 1] == "exit"
+
+
+async def test_with_pull_context_manager_exits_on_iteration_error():
+    """The pull context is exited even when the underlying stream raises mid-iteration."""
+    import contextlib
+
+    events: list[str] = []
+
+    @contextlib.contextmanager
+    def cm():
+        events.append("enter")
+        try:
+            yield
+        finally:
+            events.append("exit")
+
+    async def src() -> AsyncIterable[int]:
+        yield 1
+        raise RuntimeError("boom")
+
+    stream: ResponseStream[int, list[int]] = ResponseStream(src(), finalizer=lambda updates: list(updates))
+    stream.with_pull_context_manager(cm)
+
+    with pytest.raises(RuntimeError, match="boom"):
+        async for _ in stream:
+            pass
+
+    # Enter/exit balanced even on the failing pull.
+    assert events.count("enter") == events.count("exit")
+    assert events.count("enter") >= 2
+
+
+async def test_with_pull_context_manager_wraps_stream_resolution_via_await():
+    """Awaiting a ``from_awaitable`` stream resolves the inner stream under the pull contexts."""
+    import contextlib
+
+    events: list[str] = []
+
+    @contextlib.contextmanager
+    def cm():
+        events.append("enter")
+        try:
+            yield
+        finally:
+            events.append("exit")
+
+    async def inner() -> AsyncIterable[int]:
+        yield 1
+
+    async def make_stream() -> ResponseStream[int, list[int]]:
+        # Record that we resolve while a pull context is active.
+        events.append("resolving")
+        return ResponseStream(inner(), finalizer=lambda updates: list(updates))
+
+    stream: ResponseStream[int, list[int]] = ResponseStream.from_awaitable(make_stream())
+    stream.with_pull_context_manager(cm)
+
+    await stream  # Triggers _resolve_stream_with_pull_contexts via __await__
+
+    assert "resolving" in events
+    resolve_index = events.index("resolving")
+    assert events[resolve_index - 1] == "enter"  # Pull context active during resolution
+
+
+# region Test streaming telemetry error paths
+
+
+@pytest.mark.parametrize("enable_sensitive_data", [True], indirect=True)
+async def test_chat_streaming_super_failure_closes_span(span_exporter: InMemorySpanExporter, enable_sensitive_data):
+    """If the underlying client raises synchronously when constructing the stream, the chat
+    span is ended and the exception is recorded (no span leak)."""
+
+    class FailingClient(ChatTelemetryLayer, BaseChatClient[Any]):
+        def service_url(self):
+            return "https://test.example.com"
+
+        def _inner_get_response(
+            self, *, messages: MutableSequence[Message], stream: bool, options: dict[str, Any], **kwargs: Any
+        ) -> Awaitable[ChatResponse] | ResponseStream[ChatResponseUpdate, ChatResponse]:
+            raise RuntimeError("inner failed")
+
+    span_exporter.clear()
+    client = FailingClient()
+    with pytest.raises(RuntimeError, match="inner failed"):
+        client.get_response(stream=True, messages=[Message(role="user", contents=["Test"])], options={"model": "Test"})
+
+    spans = span_exporter.get_finished_spans()
+    chat_spans = [s for s in spans if s.attributes.get(OtelAttr.OPERATION.value) == OtelAttr.CHAT_COMPLETION_OPERATION]
+    assert len(chat_spans) == 1
+    assert chat_spans[0].status.status_code == StatusCode.ERROR
+
+
+@pytest.mark.parametrize("enable_sensitive_data", [True], indirect=True)
+async def test_agent_streaming_execute_failure_closes_span_and_resets_contextvars(
+    span_exporter: InMemorySpanExporter, enable_sensitive_data
+):
+    """If ``execute()`` raises synchronously during streaming agent invocation, the agent span is
+    ended, the exception is recorded, and the telemetry contextvars are reset."""
+    from agent_framework.observability import (
+        INNER_ACCUMULATED_USAGE,
+        INNER_RESPONSE_TELEMETRY_CAPTURED_FIELDS,
+    )
+
+    class _FailingExecuteAgent:
+        AGENT_PROVIDER_NAME = "test_provider"
+
+        def __init__(self):
+            self._id = "failing_execute"
+            self._name = "Failing Execute"
+            self._description = "Agent whose stream call raises synchronously"
+            self._default_options: dict[str, Any] = {}
+
+        @property
+        def id(self):
+            return self._id
+
+        @property
+        def name(self):
+            return self._name
+
+        @property
+        def description(self):
+            return self._description
+
+        @property
+        def default_options(self):
+            return self._default_options
+
+        def run(self, messages=None, *, stream: bool = False, session=None, **kwargs):
+            if stream:
+                raise RuntimeError("execute failed")
+            raise NotImplementedError
+
+    class FailingExecuteAgent(AgentTelemetryLayer, _FailingExecuteAgent):
+        pass
+
+    # Sentinel values to detect that contextvars were reset to their pre-call state.
+    sentinel_fields: set[str] = set()
+    sentinel_usage: dict[str, Any] = {}
+    fields_token = INNER_RESPONSE_TELEMETRY_CAPTURED_FIELDS.set(sentinel_fields)
+    usage_token = INNER_ACCUMULATED_USAGE.set(sentinel_usage)
+    try:
+        agent = FailingExecuteAgent()
+        span_exporter.clear()
+        with pytest.raises(RuntimeError, match="execute failed"):
+            agent.run(messages="Hello", stream=True)
+
+        # Contextvars must be back to the sentinel values registered before the call.
+        assert INNER_RESPONSE_TELEMETRY_CAPTURED_FIELDS.get() is sentinel_fields
+        assert INNER_ACCUMULATED_USAGE.get() is sentinel_usage
+    finally:
+        INNER_ACCUMULATED_USAGE.reset(usage_token)
+        INNER_RESPONSE_TELEMETRY_CAPTURED_FIELDS.reset(fields_token)
+
+    spans = span_exporter.get_finished_spans()
+    agent_spans = [s for s in spans if s.attributes.get(OtelAttr.OPERATION.value) == OtelAttr.AGENT_INVOKE_OPERATION]
+    assert len(agent_spans) == 1
+    assert agent_spans[0].status.status_code == StatusCode.ERROR

python/packages/core/tests/core/test_types.py

@@ -1087,16 +1087,20 @@ def test_chat_tool_mode():
     required_any: ToolMode = {"mode": "required"}
     required_mode: ToolMode = {"mode": "required", "required_function_name": "example_function"}
     none_mode: ToolMode = {"mode": "none"}
+    allowed_mode: ToolMode = {"mode": "auto", "allowed_tools": ["get_weather", "search_docs"]}
 
     # Check the type and content
     assert auto_mode["mode"] == "auto"
     assert "required_function_name" not in auto_mode
+    assert "allowed_tools" not in auto_mode
     assert required_any["mode"] == "required"
     assert "required_function_name" not in required_any
     assert required_mode["mode"] == "required"
     assert required_mode["required_function_name"] == "example_function"
     assert none_mode["mode"] == "none"
     assert "required_function_name" not in none_mode
+    assert allowed_mode["mode"] == "auto"
+    assert allowed_mode["allowed_tools"] == ["get_weather", "search_docs"]
 
     # equality of dicts
     assert {"mode": "required", "required_function_name": "example_function"} == {
@@ -1154,6 +1158,45 @@ def test_chat_options_tool_choice_validation():
     with raises(ContentError):
         validate_tool_mode({"mode": "auto", "required_function_name": "should_not_be_here"})
 
+    # Valid allowed_tools
+    assert validate_tool_mode({"mode": "auto", "allowed_tools": ["get_weather"]}) == {
+        "mode": "auto",
+        "allowed_tools": ["get_weather"],
+    }
+    assert validate_tool_mode({"mode": "auto", "allowed_tools": ["get_weather", "search_docs"]}) == {
+        "mode": "auto",
+        "allowed_tools": ["get_weather", "search_docs"],
+    }
+
+    # allowed_tools valid with required mode
+    assert validate_tool_mode({"mode": "required", "allowed_tools": ["get_weather"]}) == {
+        "mode": "required",
+        "allowed_tools": ["get_weather"],
+    }
+
+    # allowed_tools invalid with none mode
+    with raises(ContentError):
+        validate_tool_mode({"mode": "none", "allowed_tools": ["get_weather"]})
+
+    # allowed_tools must be a non-string sequence of strings
+    with raises(ContentError):
+        validate_tool_mode({"mode": "auto", "allowed_tools": "get_weather"})
+    with raises(ContentError):
+        validate_tool_mode({"mode": "auto", "allowed_tools": 123})
+    with raises(ContentError):
+        validate_tool_mode({"mode": "auto", "allowed_tools": ["get_weather", 123]})
+
+    # Empty list is valid (caller explicitly allows no tools)
+    assert validate_tool_mode({"mode": "auto", "allowed_tools": []}) == {
+        "mode": "auto",
+        "allowed_tools": [],
+    }
+
+    # Tuple is normalized to list
+    result = validate_tool_mode({"mode": "auto", "allowed_tools": ("get_weather",)})
+    assert result is not None
+    assert result["allowed_tools"] == ["get_weather"]
+
 
 def test_chat_options_merge(tool_tool, ai_tool) -> None:
     """Test merge_chat_options utility function."""

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

@@ -488,8 +488,13 @@ class StateTrackingExecutor(Executor):
         await ctx.yield_output(existing_messages.copy())  # type: ignore
 
 
-async def test_workflow_multiple_runs_no_state_collision():
-    """Test that running the same workflow instance multiple times doesn't have state collision."""
+async def test_workflow_multiple_runs_preserve_state():
+    """Test that running the same workflow instance multiple times preserves shared state.
+
+    State preservation is the new default - calling ``Workflow.run`` repeatedly
+    on the same instance behaves like a chat agent maintaining memory across
+    turns. Callers that want fresh state should rebuild the Workflow.
+    """
     with tempfile.TemporaryDirectory() as temp_dir:
         storage = FileCheckpointStorage(temp_dir)
 
@@ -503,29 +508,45 @@ async def test_workflow_multiple_runs_no_state_collision():
             .build()
         )
 
-        # Run 1: Should only see messages from run 1
+        # Run 1: Single record from run 1
         result1 = await workflow.run(StateTrackingMessage(data="message1", run_id="run1"))
         assert result1.get_final_state() == WorkflowRunState.IDLE
         outputs1 = result1.get_outputs()
         assert outputs1[0] == ["run1:message1"]
 
-        # Run 2: Should only see messages from run 2, not run 1
+        # Run 2: State from run 1 persists; run 2's record appends.
         result2 = await workflow.run(StateTrackingMessage(data="message2", run_id="run2"))
         assert result2.get_final_state() == WorkflowRunState.IDLE
         outputs2 = result2.get_outputs()
-        assert outputs2[0] == ["run2:message2"]  # Should NOT contain run1 data
+        assert outputs2[0] == ["run1:message1", "run2:message2"]
 
-        # Run 3: Should only see messages from run 3
+        # Run 3: Same - all three accumulate.
         result3 = await workflow.run(StateTrackingMessage(data="message3", run_id="run3"))
         assert result3.get_final_state() == WorkflowRunState.IDLE
         outputs3 = result3.get_outputs()
-        assert outputs3[0] == ["run3:message3"]  # Should NOT contain run1 or run2 data
+        assert outputs3[0] == ["run1:message1", "run2:message2", "run3:message3"]
 
-        # Verify that each run only processed its own message
-        # This confirms that the checkpointable context properly resets between runs
-        assert outputs1[0] != outputs2[0]
-        assert outputs2[0] != outputs3[0]
-        assert outputs1[0] != outputs3[0]
+
+async def test_workflow_multiple_runs_no_state_collision_after_rebuild():
+    """Rebuilding the Workflow gives a fresh shared-state slate."""
+    with tempfile.TemporaryDirectory() as temp_dir:
+        storage = FileCheckpointStorage(temp_dir)
+
+        def _build():
+            executor = StateTrackingExecutor(id="state_executor")
+            return (
+                WorkflowBuilder(start_executor=executor, checkpoint_storage=storage)
+                .add_edge(executor, executor)
+                .build()
+            )
+
+        wf1 = _build()
+        result1 = await wf1.run(StateTrackingMessage(data="message1", run_id="run1"))
+        assert result1.get_outputs()[0] == ["run1:message1"]
+
+        wf2 = _build()
+        result2 = await wf2.run(StateTrackingMessage(data="message2", run_id="run2"))
+        assert result2.get_outputs()[0] == ["run2:message2"]
 
 
 async def test_workflow_checkpoint_runtime_only_configuration(
@@ -932,6 +953,31 @@ async def test_agent_streaming_vs_non_streaming() -> None:
     assert accumulated_text == "Hello World", f"Expected 'Hello World', got '{accumulated_text}'"
 
 
+async def test_workflow_run_inflight_messages_guard(simple_executor: Executor) -> None:
+    """``run(message=...)`` must reject in-flight executor messages from a prior run.
+
+    Workflows preserve state and pending messages across :meth:`Workflow.run`
+    calls. If a prior run aborted before the runner drained those pending
+    messages (e.g. it raised :class:`WorkflowConvergenceException`), the next
+    fresh-message call should fail loudly instead of silently mixing the
+    leftover messages with the new turn. The supported recovery path is to
+    resume from a checkpoint; there is no in-process recovery hatch.
+    """
+    workflow = WorkflowBuilder(start_executor=simple_executor).add_edge(simple_executor, simple_executor).build()
+    test_message = WorkflowMessage(data="test", source_id="test", target_id=None)
+
+    # Simulate an aborted prior run by leaving a message in the runner context.
+    workflow._runner.context._messages["test"] = [test_message]
+    assert await workflow._runner.context.has_messages()
+
+    with pytest.raises(RuntimeError, match="in-flight executor messages"):
+        await workflow.run(test_message)
+
+    with pytest.raises(RuntimeError, match="in-flight executor messages"):
+        async for _ in workflow.run(test_message, stream=True):
+            pass
+
+
 async def test_workflow_run_parameter_validation(simple_executor: Executor) -> None:
     """Test that stream properly validate parameter combinations."""
     workflow = WorkflowBuilder(start_executor=simple_executor).add_edge(simple_executor, simple_executor).build()
@@ -942,13 +988,15 @@ async def test_workflow_run_parameter_validation(simple_executor: Executor) -> N
     result = await workflow.run(test_message)
     assert result.get_final_state() == WorkflowRunState.IDLE
 
-    # Invalid: both message and checkpoint_id
+    # Invalid: message + checkpoint_id (mutually exclusive). Multi-turn
+    # state preservation is handled by Workflow.run preserving state across
+    # calls, so the host pattern is two separate calls (restore-then-run),
+    # not a single combined call.
     with pytest.raises(ValueError, match="Cannot provide both 'message' and 'checkpoint_id'"):
-        await workflow.run(test_message, checkpoint_id="fake_id")
+        await workflow.run(test_message, checkpoint_id="some-checkpoint")
 
-    # Invalid: both message and checkpoint_id (streaming)
     with pytest.raises(ValueError, match="Cannot provide both 'message' and 'checkpoint_id'"):
-        async for _ in workflow.run(test_message, checkpoint_id="fake_id", stream=True):
+        async for _ in workflow.run(test_message, checkpoint_id="some-checkpoint", stream=True):
             pass
 
     # Invalid: none of message or checkpoint_id

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

@@ -232,16 +232,18 @@ async def test_groupchat_kwargs_flow_to_agents() -> None:
 
 async def test_kwargs_stored_in_state() -> None:
     """Test that function_invocation_kwargs are stored in State with the correct key."""
-    from agent_framework import Executor, WorkflowContext, handler
+    from typing_extensions import Never
+
+    from agent_framework import AgentResponse, Executor, WorkflowContext, handler
 
     stored_kwargs: dict[str, Any] | None = None
 
     class _StateInspector(Executor):
         @handler
-        async def inspect(self, msgs: list[Message], ctx: WorkflowContext[list[Message]]) -> None:
+        async def inspect(self, msgs: list[Message], ctx: WorkflowContext[Never, AgentResponse]) -> None:
             nonlocal stored_kwargs
             stored_kwargs = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY)
-            await ctx.send_message(msgs)
+            await ctx.yield_output(AgentResponse(messages=msgs))
 
     inspector = _StateInspector(id="inspector")
     workflow = SequentialBuilder(participants=[inspector]).build()
@@ -256,16 +258,18 @@ async def test_kwargs_stored_in_state() -> None:
 
 async def test_empty_kwargs_stored_as_empty_dict() -> None:
     """Test that empty kwargs are stored as empty dict in State."""
-    from agent_framework import Executor, WorkflowContext, handler
+    from typing_extensions import Never
+
+    from agent_framework import AgentResponse, Executor, WorkflowContext, handler
 
     stored_kwargs: Any = "NOT_CHECKED"
 
     class _StateChecker(Executor):
         @handler
-        async def check(self, msgs: list[Message], ctx: WorkflowContext[list[Message]]) -> None:
+        async def check(self, msgs: list[Message], ctx: WorkflowContext[Never, AgentResponse]) -> None:
             nonlocal stored_kwargs
             stored_kwargs = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY)
-            await ctx.send_message(msgs)
+            await ctx.yield_output(AgentResponse(messages=msgs))
 
     checker = _StateChecker(id="checker")
     workflow = SequentialBuilder(participants=[checker]).build()
@@ -695,7 +699,9 @@ async def test_subworkflow_kwargs_accessible_via_state() -> None:
     Verifies that WORKFLOW_RUN_KWARGS_KEY is populated in the subworkflow's State
     with kwargs from the parent workflow.
     """
-    from agent_framework import Executor, WorkflowContext, handler
+    from typing_extensions import Never
+
+    from agent_framework import AgentResponse, Executor, WorkflowContext, handler
     from agent_framework._workflows._workflow_executor import WorkflowExecutor
 
     captured_kwargs_from_state: list[dict[str, Any]] = []
@@ -704,10 +710,10 @@ async def test_subworkflow_kwargs_accessible_via_state() -> None:
         """Executor that reads kwargs from State for verification."""
 
         @handler
-        async def read_kwargs(self, msgs: list[Message], ctx: WorkflowContext[list[Message]]) -> None:
+        async def read_kwargs(self, msgs: list[Message], ctx: WorkflowContext[Never, AgentResponse]) -> None:
             kwargs_from_state = ctx.get_state(WORKFLOW_RUN_KWARGS_KEY)
             captured_kwargs_from_state.append(kwargs_from_state or {})
-            await ctx.send_message(msgs)
+            await ctx.yield_output(AgentResponse(messages=msgs))
 
     # Build inner workflow with State reader
     state_reader = _StateReader(id="state_reader")

python/packages/declarative/AGENTS.md

@@ -8,7 +8,8 @@ YAML/JSON-based declarative agent and workflow definitions.
 - **`WorkflowFactory`** - Creates workflows from declarative definitions
 - **`WorkflowState`** - State management for declarative workflows
 - **`ProviderTypeMapping`** - Maps provider types to implementations
-- **`DeclarativeLoaderError`** / **`ProviderLookupError`** - Error types
+- **`HttpRequestHandler`** / **`DefaultHttpRequestHandler`** - Pluggable HTTP transport for the `HttpRequestAction` declarative action (configured via `WorkflowFactory(http_request_handler=...)`)
+- **`DeclarativeLoaderError`** / **`ProviderLookupError`** / **`DeclarativeWorkflowError`** / **`DeclarativeActionError`** - Error types
 
 ## External Input Handling
 

python/packages/declarative/agent_framework_declarative/__init__.py

@@ -6,9 +6,14 @@ from ._loader import AgentFactory, DeclarativeLoaderError, ProviderLookupError,
 from ._workflows import (
     AgentExternalInputRequest,
     AgentExternalInputResponse,
+    DeclarativeActionError,
     DeclarativeWorkflowError,
+    DefaultHttpRequestHandler,
     ExternalInputRequest,
     ExternalInputResponse,
+    HttpRequestHandler,
+    HttpRequestInfo,
+    HttpRequestResult,
     WorkflowFactory,
     WorkflowState,
 )
@@ -22,10 +27,15 @@ __all__ = [
     "AgentExternalInputRequest",
     "AgentExternalInputResponse",
     "AgentFactory",
+    "DeclarativeActionError",
     "DeclarativeLoaderError",
     "DeclarativeWorkflowError",
+    "DefaultHttpRequestHandler",
     "ExternalInputRequest",
     "ExternalInputResponse",
+    "HttpRequestHandler",
+    "HttpRequestInfo",
+    "HttpRequestResult",
     "ProviderLookupError",
     "ProviderTypeMapping",
     "WorkflowFactory",

python/packages/declarative/agent_framework_declarative/_workflows/__init__.py

@@ -25,6 +25,7 @@ from ._declarative_base import (
     LoopIterationResult,
 )
 from ._declarative_builder import ALL_ACTION_EXECUTORS, DeclarativeWorkflowBuilder
+from ._errors import DeclarativeActionError, DeclarativeWorkflowError
 from ._executors_agents import (
     AGENT_ACTION_EXECUTORS,
     AGENT_REGISTRY_KEY,
@@ -67,6 +68,10 @@ from ._executors_external_input import (
     RequestExternalInputExecutor,
     WaitForInputExecutor,
 )
+from ._executors_http import (
+    HTTP_ACTION_EXECUTORS,
+    HttpRequestActionExecutor,
+)
 from ._executors_tools import (
     FUNCTION_TOOL_REGISTRY_KEY,
     TOOL_ACTION_EXECUTORS,
@@ -78,7 +83,13 @@ from ._executors_tools import (
     ToolApprovalState,
     ToolInvocationResult,
 )
-from ._factory import DeclarativeWorkflowError, WorkflowFactory
+from ._factory import WorkflowFactory
+from ._http_handler import (
+    DefaultHttpRequestHandler,
+    HttpRequestHandler,
+    HttpRequestInfo,
+    HttpRequestResult,
+)
 from ._state import WorkflowState
 
 __all__ = [
@@ -90,6 +101,7 @@ __all__ = [
     "DECLARATIVE_STATE_KEY",
     "EXTERNAL_INPUT_EXECUTORS",
     "FUNCTION_TOOL_REGISTRY_KEY",
+    "HTTP_ACTION_EXECUTORS",
     "TOOL_ACTION_EXECUTORS",
     "TOOL_APPROVAL_STATE_KEY",
     "TOOL_REGISTRY_KEY",
@@ -106,12 +118,14 @@ __all__ = [
     "ContinueLoopExecutor",
     "ConversationData",
     "CreateConversationExecutor",
+    "DeclarativeActionError",
     "DeclarativeActionExecutor",
     "DeclarativeMessage",
     "DeclarativeStateData",
     "DeclarativeWorkflowBuilder",
     "DeclarativeWorkflowError",
     "DeclarativeWorkflowState",
+    "DefaultHttpRequestHandler",
     "EmitEventExecutor",
     "EndConversationExecutor",
     "EndWorkflowExecutor",
@@ -120,6 +134,10 @@ __all__ = [
     "ExternalLoopState",
     "ForeachInitExecutor",
     "ForeachNextExecutor",
+    "HttpRequestActionExecutor",
+    "HttpRequestHandler",
+    "HttpRequestInfo",
+    "HttpRequestResult",
     "InvokeAzureAgentExecutor",
     "InvokeFunctionToolExecutor",
     "JoinExecutor",

python/packages/declarative/agent_framework_declarative/_workflows/_declarative_base.py

@@ -32,10 +32,12 @@ import uuid
 from collections.abc import Mapping
 from dataclasses import dataclass
 from decimal import Decimal as _Decimal
+from enum import Enum
 from typing import Any, Literal, cast
 
 from agent_framework import (
     Executor,
+    Message,
     WorkflowContext,
 )
 from agent_framework._workflows._state import State
@@ -120,7 +122,20 @@ def _make_powerfx_safe(value: Any) -> Any:
     Returns:
         A PowerFx-safe representation of the value
     """
-    if value is None or isinstance(value, _POWERFX_SAFE_TYPES):
+    if value is None:
+        return value
+
+    # Enum coercion must run BEFORE the primitive type check: many MAF
+    # enums (e.g. MessageRole) are ``str``-subclass enums, so they pass
+    # ``isinstance(v, str)`` but pythonnet refuses to convert them to
+    # ``System.String`` and raises ``'MessageRole' value cannot be
+    # converted to System.<X>'`` for every PowerFx primitive type. Reduce
+    # to the underlying value (or its string form) so PowerFx sees a
+    # plain ``str``/``int``.
+    if isinstance(value, Enum):
+        return _make_powerfx_safe(value.value)
+
+    if isinstance(value, _POWERFX_SAFE_TYPES):
         return value
 
     if isinstance(value, dict):
@@ -197,6 +212,16 @@ class DeclarativeWorkflowState:
             result = self._state.get(DECLARATIVE_STATE_KEY)
         return cast(DeclarativeStateData, result)
 
+    def is_initialized(self) -> bool:
+        """Return True when declarative state has been initialized.
+
+        Useful for distinguishing a fresh start from a continuation: when
+        Workflow state preserves data across run() calls (multi-turn
+        scenarios), the start executor needs to avoid calling initialize()
+        and clobbering the prior turn's Conversation/Local/System data.
+        """
+        return self._state.get(DECLARATIVE_STATE_KEY) is not None
+
     def set_state_data(self, data: DeclarativeStateData) -> None:
         """Set the full state data dict in state."""
         self._state.set(DECLARATIVE_STATE_KEY, data)
@@ -873,6 +898,20 @@ class DeclarativeActionExecutor(Executor):
         Follows .NET's DefaultTransform pattern - accepts any input type:
         - dict/Mapping: Used directly as workflow.inputs
         - str: Converted to {"input": value}
+        - list[Message]: Treated as the agent-facing message contract
+          (e.g. from WorkflowAgent / as_agent()). The prior conversation
+          history is stored in ``Conversation.messages``/
+          ``Conversation.history`` and mirrored to
+          ``System.conversations.{id}.messages`` so workflows that
+          reference ``=Conversation.messages`` (e.g. InvokeAzureAgent) see
+          assistant turns and other earlier messages, including non-text
+          content. At the start of a turn this history excludes the current
+          user message; that message's text is instead used as the string
+          input (``Inputs.input``) and surfaced via ``System.LastMessage*``
+          for backward compatibility with simple text-only workflows. Agent
+          executors are responsible for appending the current user message
+          to ``Conversation.messages`` immediately before invoking the
+          inner agent.
         - DeclarativeMessage: Internal message, no initialization needed
         - Any other type: Converted via str() to {"input": str(value)}
 
@@ -888,6 +927,100 @@ class DeclarativeActionExecutor(Executor):
         if isinstance(trigger, dict):
             # Structured inputs - use directly
             state.initialize(trigger)  # type: ignore
+        elif isinstance(trigger, list) and all(isinstance(m, Message) for m in trigger):  # pyright: ignore[reportUnknownVariableType]
+            # list[Message] (e.g. from WorkflowAgent / as_agent()).
+            messages_list = cast(list[Message], trigger)
+
+            # Detect continuation: if the workflow's shared state already
+            # carries declarative data from a prior turn (because the host
+            # restored a checkpoint and dispatched this run with
+            # reset_context=False), we MUST NOT call state.initialize() -
+            # that would wipe Conversation.messages, Local.*, System.* etc.
+            # Instead, treat the trigger as the new turn's user input only:
+            # update Inputs.input, append the new user message to existing
+            # Conversation history, and refresh System.LastMessage*.
+            #
+            # Continuation = declarative state already exists in the workflow's
+            # shared state (either left over in-memory from a prior turn on
+            # the same instance, or restored from a checkpoint just before
+            # this run). In that case state.initialize() would wipe Local.*,
+            # System.*, Conversation.* etc., destroying the cross-turn
+            # context we're trying to preserve.
+            is_continuation = state.is_initialized()
+
+            # Locate the trailing user message in the trigger.
+            last_user_index = -1
+            for idx in range(len(messages_list) - 1, -1, -1):
+                if str(messages_list[idx].role).lower() == "user":
+                    last_user_index = idx
+                    break
+
+            if last_user_index >= 0:
+                last_user_msg = messages_list[last_user_index]
+                last_user_text = last_user_msg.text or ""
+                last_user_id = getattr(last_user_msg, "message_id", "") or ""
+                history_messages = messages_list[:last_user_index] + messages_list[last_user_index + 1 :]
+            else:
+                history_messages = list(messages_list)
+                tail = messages_list[-1] if messages_list else None
+                last_user_text = (tail.text or "") if tail is not None else ""
+                last_user_id = getattr(tail, "message_id", "") or "" if tail is not None else ""
+
+            if is_continuation:
+                # Continuation turn: keep prior Conversation.messages intact.
+                # Refresh inputs and surface the new user message via the
+                # System.LastMessage* fields. We deliberately do NOT append
+                # the new user message to Conversation.messages here: agent
+                # executors append the live user input themselves before
+                # invoking the inner agent (matching the first-turn
+                # contract where Conversation.messages holds prior turns
+                # only).
+                #
+                # Note: ``state.set("Inputs.input", ...)`` would route to
+                # the Custom namespace (Inputs is not a recognized top-level
+                # writable namespace - see DeclarativeWorkflowState.set).
+                # PowerFx expressions like ``=Workflow.Inputs.input`` /
+                # ``=inputs.input`` read state_data["Inputs"] directly, so
+                # we update that dict in place via get_state_data /
+                # set_state_data.
+                state_data = state.get_state_data()
+                inputs_dict = state_data.get("Inputs")
+                if not isinstance(inputs_dict, dict):
+                    inputs_dict = {}
+                    state_data["Inputs"] = inputs_dict
+                inputs_dict["input"] = last_user_text
+                state.set_state_data(state_data)
+                # Trailing non-user messages (e.g. tool results) sandwiched
+                # before the new user message in the trigger are still
+                # appended so later actions see them.
+                for msg in history_messages:
+                    state.append("Conversation.messages", msg)
+                    state.append("Conversation.history", msg)
+                conversation_id = state.get("System.ConversationId")
+                if conversation_id:
+                    conv_path = f"System.conversations.{conversation_id}.messages"
+                    for msg in history_messages:
+                        state.append(conv_path, msg)
+                state.set("System.LastMessage", {"Text": last_user_text, "Id": last_user_id})
+                state.set("System.LastMessageText", last_user_text)
+                state.set("System.LastMessageId", last_user_id)
+            else:
+                # First turn: full initialization.
+                state.initialize({"input": last_user_text})
+
+                for msg in history_messages:
+                    state.append("Conversation.messages", msg)
+                    state.append("Conversation.history", msg)
+
+                conversation_id = state.get("System.ConversationId")
+                if conversation_id:
+                    conv_path = f"System.conversations.{conversation_id}.messages"
+                    for msg in history_messages:
+                        state.append(conv_path, msg)
+
+                state.set("System.LastMessage", {"Text": last_user_text, "Id": last_user_id})
+                state.set("System.LastMessageText", last_user_text)
+                state.set("System.LastMessageId", last_user_id)
         elif isinstance(trigger, str):
             # String input - wrap in dict and populate System.LastMessage.Text
             # so YAML expressions like =System.LastMessage.Text see the user input
@@ -895,10 +1028,11 @@ class DeclarativeActionExecutor(Executor):
             state.set("System.LastMessage", {"Text": trigger, "Id": ""})
             state.set("System.LastMessageText", trigger)
         elif not isinstance(
-            trigger, (ActionTrigger, ActionComplete, ConditionResult, LoopIterationResult, LoopControl)
+            trigger,
+            (ActionTrigger, ActionComplete, ConditionResult, LoopIterationResult, LoopControl),  # pyright: ignore[reportUnknownArgumentType]
         ):
             # Any other type - convert to string like .NET's DefaultTransform
-            input_str = str(trigger)
+            input_str = str(cast(Any, trigger))
             state.initialize({"input": input_str})
             state.set("System.LastMessage", {"Text": input_str, "Id": ""})
             state.set("System.LastMessageText", input_str)

python/packages/declarative/agent_framework_declarative/_workflows/_declarative_builder.py

@@ -26,6 +26,7 @@ from ._declarative_base import (
     DeclarativeActionExecutor,
     LoopIterationResult,
 )
+from ._errors import DeclarativeWorkflowError
 from ._executors_agents import AGENT_ACTION_EXECUTORS, InvokeAzureAgentExecutor
 from ._executors_basic import BASIC_ACTION_EXECUTORS
 from ._executors_control_flow import (
@@ -39,7 +40,9 @@ from ._executors_control_flow import (
     SwitchEvaluatorExecutor,
 )
 from ._executors_external_input import EXTERNAL_INPUT_EXECUTORS
+from ._executors_http import HTTP_ACTION_EXECUTORS, HttpRequestActionExecutor
 from ._executors_tools import TOOL_ACTION_EXECUTORS, InvokeFunctionToolExecutor
+from ._http_handler import HttpRequestHandler
 
 logger = logging.getLogger(__name__)
 
@@ -51,6 +54,7 @@ ALL_ACTION_EXECUTORS = {
     **AGENT_ACTION_EXECUTORS,
     **EXTERNAL_INPUT_EXECUTORS,
     **TOOL_ACTION_EXECUTORS,
+    **HTTP_ACTION_EXECUTORS,
 }
 
 # Action kinds that terminate control flow (no fall-through to successor)
@@ -85,6 +89,7 @@ ACTION_REQUIRED_FIELDS: dict[str, list[str]] = {
     "WaitForHumanInput": ["variable"],
     "EmitEvent": ["event"],
     "InvokeFunctionTool": ["functionName"],
+    "HttpRequestAction": ["url"],
 }
 
 # Alternate field names that satisfy required field requirements
@@ -129,6 +134,7 @@ class DeclarativeWorkflowBuilder:
         checkpoint_storage: Any | None = None,
         validate: bool = True,
         max_iterations: int | None = None,
+        http_request_handler: HttpRequestHandler | None = None,
     ):
         """Initialize the builder.
 
@@ -141,6 +147,9 @@ class DeclarativeWorkflowBuilder:
             validate: Whether to validate the workflow definition before building (default: True)
             max_iterations: Maximum runner supersteps. Falls back to the YAML ``maxTurns``
                 field, then to the core default (100).
+            http_request_handler: Handler used to dispatch HttpRequestAction requests.
+                Must be supplied when the workflow contains any HttpRequestAction;
+                otherwise build raises ``DeclarativeWorkflowError``.
         """
         self._yaml_def = yaml_definition
         self._workflow_id = workflow_id or yaml_definition.get("name", "declarative_workflow")
@@ -152,6 +161,7 @@ class DeclarativeWorkflowBuilder:
         self._pending_gotos: list[tuple[Any, str]] = []  # (goto_executor, target_id)
         self._validate = validate
         self._seen_explicit_ids: set[str] = set()  # Track explicit IDs for duplicate detection
+        self._http_request_handler = http_request_handler
         # Resolve max_iterations: explicit arg > YAML maxTurns > core default
         resolved = max_iterations if max_iterations is not None else yaml_definition.get("maxTurns")
         if resolved is not None and (not isinstance(resolved, int) or resolved <= 0):
@@ -458,6 +468,19 @@ class DeclarativeWorkflowBuilder:
             executor = InvokeAzureAgentExecutor(action_def, id=action_id, agents=self._agents)
         elif kind == "InvokeFunctionTool":
             executor = InvokeFunctionToolExecutor(action_def, id=action_id, tools=self._tools)
+        elif kind == "HttpRequestAction":
+            if self._http_request_handler is None:
+                raise DeclarativeWorkflowError(
+                    f"Workflow defines HttpRequestAction '{action_id}' but no "
+                    "http_request_handler was supplied to WorkflowFactory. Pass "
+                    "http_request_handler=DefaultHttpRequestHandler() (or a custom "
+                    "implementation) to enable HTTP requests."
+                )
+            executor = HttpRequestActionExecutor(
+                action_def,
+                id=action_id,
+                http_request_handler=self._http_request_handler,
+            )
         else:
             executor = executor_class(action_def, id=action_id)
         self._executors[action_id] = executor

python/packages/declarative/agent_framework_declarative/_workflows/_errors.py

@@ -0,0 +1,38 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Error types for declarative workflow executor modules.
+
+This module exists so that executor modules and the builder (e.g.
+``_executors_http``, ``_declarative_builder``) can raise declarative-specific
+exceptions without importing from ``_factory``. ``_factory`` imports
+``_declarative_builder`` which imports the executor modules; pulling
+:class:`DeclarativeWorkflowError` from ``_factory`` into an executor or
+builder module would therefore introduce a circular import.
+"""
+
+from __future__ import annotations
+
+from agent_framework.exceptions import WorkflowException
+
+
+class DeclarativeWorkflowError(WorkflowException):
+    """Raised for build-time / factory-level declarative workflow errors.
+
+    Used for YAML parsing/validation issues, missing configuration (e.g. an
+    HTTP request handler not supplied for a workflow that contains an
+    ``HttpRequestAction``), and other errors detected before workflow
+    execution begins.
+    """
+
+    pass
+
+
+class DeclarativeActionError(WorkflowException):
+    """Raised when a declarative action fails at run time.
+
+    Used by executor modules for runtime failures (e.g. transport errors,
+    non-2xx responses from :class:`HttpRequestActionExecutor`). Build-time and
+    factory-level errors continue to use :class:`DeclarativeWorkflowError`.
+    """
+
+    pass

python/packages/declarative/agent_framework_declarative/_workflows/_executors_control_flow.py

@@ -17,6 +17,7 @@ The key insight is that control flow becomes GRAPH STRUCTURE, not executor logic
 from typing import Any, cast
 
 from agent_framework import (
+    Message,
     WorkflowContext,
     handler,
 )
@@ -492,7 +493,13 @@ class JoinExecutor(DeclarativeActionExecutor):
     @handler
     async def handle_action(
         self,
-        trigger: dict[str, Any] | str | ActionTrigger | ActionComplete | ConditionResult | LoopIterationResult,
+        trigger: dict[str, Any]
+        | str
+        | list[Message]
+        | ActionTrigger
+        | ActionComplete
+        | ConditionResult
+        | LoopIterationResult,
         ctx: WorkflowContext[ActionComplete],
     ) -> None:
         """Simply pass through to continue the workflow."""

python/packages/declarative/agent_framework_declarative/_workflows/_executors_http.py

@@ -0,0 +1,417 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Executor for the ``HttpRequestAction`` declarative action.
+
+Mirrors the .NET ``HttpRequestExecutor``: dispatches an HTTP request through the
+configured :class:`HttpRequestHandler`, parses the response body, and assigns
+the parsed body and response headers to the declared state paths.
+
+Security note: response bodies can echo secrets and may be very large. Diagnostic
+messages produced for non-2xx responses truncate the body to 256 characters and
+collapse CR/LF/TAB to spaces (parity with .NET ``FormatBodyForDiagnostics``).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+from agent_framework import (
+    Message,
+    WorkflowContext,
+    handler,
+)
+
+from ._declarative_base import (
+    ActionComplete,
+    DeclarativeActionExecutor,
+    DeclarativeWorkflowState,
+)
+from ._errors import DeclarativeActionError
+from ._http_handler import HttpRequestHandler, HttpRequestInfo, HttpRequestResult
+
+__all__ = [
+    "HTTP_ACTION_EXECUTORS",
+    "HttpRequestActionExecutor",
+]
+
+logger = logging.getLogger(__name__)
+
+_MAX_BODY_DIAGNOSTIC_LENGTH = 256
+_BODY_TRUNCATION_SUFFIX = " \u2026 [truncated]"
+
+
+# Body discriminator aliases. Long forms match the .NET object-model type
+# names so YAML produced by .NET round-trips. Short forms are the .NET YAML
+# convention used in test fixtures.
+_BODY_KIND_JSON = {"json", "JsonRequestContent"}
+_BODY_KIND_RAW = {"raw", "RawRequestContent"}
+_BODY_KIND_NONE = {"none", "NoRequestContent"}
+
+
+def _get_path(action_def: Mapping[str, Any], key: str) -> str | None:
+    """Extract a state path from ``response``/``responseHeaders`` field.
+
+    Supports two YAML shapes (matches .NET serialization round-trips):
+
+    - ``response: Local.MyVar`` (plain string).
+    - ``response: { path: Local.MyVar }`` (object form).
+    """
+    value = action_def.get(key)
+    if isinstance(value, str):
+        return value or None
+    if isinstance(value, Mapping):
+        path = value.get("path")  # type: ignore[reportUnknownMemberType, reportUnknownVariableType]
+        return path if isinstance(path, str) and path else None
+    return None
+
+
+def _format_body_for_diagnostics(body: str | None) -> str:
+    """Truncate and sanitise a response body for inclusion in error messages.
+
+    Mirrors the .NET ``FormatBodyForDiagnostics`` helper:
+
+    - Empty/None -> empty string.
+    - Replaces CR/LF/TAB with spaces.
+    - Truncates to 256 chars with a unicode-ellipsis ``[truncated]`` suffix.
+    """
+    if not body:
+        return ""
+
+    truncated = len(body) > _MAX_BODY_DIAGNOSTIC_LENGTH
+    head = body[:_MAX_BODY_DIAGNOSTIC_LENGTH] if truncated else body
+    sanitized = head.replace("\r", " ").replace("\n", " ").replace("\t", " ")
+    return sanitized + _BODY_TRUNCATION_SUFFIX if truncated else sanitized
+
+
+def _parse_response_body(body: str | None) -> Any:
+    """Parse an HTTP response body the same way the .NET executor does.
+
+    JSON-first: if the body parses as JSON, the parsed value is returned. Other
+    bodies are returned as the raw string. Empty/None bodies return ``None``.
+    """
+    if body is None or body == "":
+        return None
+    try:
+        return json.loads(body)
+    except json.JSONDecodeError:
+        return body
+
+
+def _format_query_value(value: Any) -> str | None:
+    """Format a query-parameter value for URL inclusion.
+
+    Mirrors .NET ``FormatQueryValue``: ``None`` is dropped, ``bool`` becomes
+    lower-case ``"true"``/``"false"``, numerics use invariant ``str()``, and
+    other values fall through to ``str()``.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return value
+    return str(value)
+
+
+def _get_messages_path(state: DeclarativeWorkflowState, conversation_id_expr: str | None) -> str | None:
+    """Return the configured conversation messages path, if any.
+
+    Returns ``System.conversations.{evaluated_id}.messages`` when a
+    ``conversation_id_expr`` is configured and evaluates to a non-empty value.
+    Returns ``None`` when no conversation id expression is configured or when
+    the expression evaluates to ``None`` or an empty string (matches .NET
+    ``GetConversationId`` behaviour where empty becomes ``null`` and the
+    response is not appended).
+    """
+    if not conversation_id_expr:
+        return None
+    evaluated = state.eval_if_expression(conversation_id_expr)
+    if evaluated is None or (isinstance(evaluated, str) and not evaluated):
+        return None
+    return f"System.conversations.{evaluated}.messages"
+
+
+class HttpRequestActionExecutor(DeclarativeActionExecutor):
+    """Executor for the ``HttpRequestAction`` declarative action.
+
+    Dispatches through the supplied :class:`HttpRequestHandler` and:
+
+    - Parses the response body (JSON-first, raw string fall-back).
+    - Assigns the parsed body to ``response`` path (if configured).
+    - Folds multi-value response headers (comma-joined) and assigns them to
+      ``responseHeaders`` path (if configured).
+    - On 2xx with non-empty body and a configured ``conversationId``, appends
+      an Assistant :class:`agent_framework.Message` to
+      ``System.conversations.{id}.messages``.
+    - On non-2xx, still publishes ``responseHeaders`` (diagnostic) and raises
+      :class:`DeclarativeActionError` with a status-coded message containing a
+      truncated/sanitised body preview.
+
+    Transport errors (``httpx.TimeoutException``, ``TimeoutError``,
+    ``httpx.HTTPError``) become :class:`DeclarativeActionError`. ``CancelledError``
+    is intentionally NOT caught so that workflow cancellation propagates.
+    """
+
+    def __init__(
+        self,
+        action_def: dict[str, Any],
+        *,
+        id: str | None = None,
+        http_request_handler: HttpRequestHandler,
+    ) -> None:
+        """Create an HTTP request action executor.
+
+        Args:
+            action_def: Parsed ``HttpRequestAction`` YAML dict.
+            id: Optional executor id (defaults to action id or generated).
+            http_request_handler: Handler used to dispatch HTTP requests.
+                Required: the builder enforces presence at workflow-build time.
+        """
+        super().__init__(action_def, id=id)
+        self._http_request_handler = http_request_handler
+
+    @handler
+    async def handle_action(
+        self,
+        trigger: Any,
+        ctx: WorkflowContext[ActionComplete],
+    ) -> None:
+        """Execute the HTTP request action."""
+        state = await self._ensure_state_initialized(ctx, trigger)
+
+        method = self._get_method(state)
+        url = self._get_url(state)
+        headers = self._get_headers(state)
+        query_parameters = self._get_query_parameters(state)
+        body, body_content_type = self._get_body(state)
+        timeout_ms = self._get_timeout_ms(state)
+        conversation_id_expr = self._action_def.get("conversationId")
+        connection_name = self._get_connection_name(state)
+
+        info = HttpRequestInfo(
+            method=method,
+            url=url,
+            headers=headers or {},
+            query_parameters=query_parameters or {},
+            body=body,
+            body_content_type=body_content_type,
+            timeout_ms=timeout_ms,
+            connection_name=connection_name,
+        )
+
+        try:
+            result = await self._http_request_handler.send(info)
+        except (httpx.TimeoutException, TimeoutError) as exc:
+            raise DeclarativeActionError(f"HTTP request to '{url}' timed out.") from exc
+        except DeclarativeActionError:
+            raise
+        except httpx.HTTPError as exc:
+            raise DeclarativeActionError(f"HTTP request to '{url}' failed: {type(exc).__name__}") from exc
+        except Exception as exc:
+            # Custom HttpRequestHandler implementations may raise arbitrary
+            # exception types. Wrap them in DeclarativeActionError so workflow
+            # error handling stays uniform regardless of transport. Note that
+            # ``asyncio.CancelledError`` is a ``BaseException`` (not
+            # ``Exception``) and so still propagates unmodified, preserving
+            # workflow-cancellation semantics.
+            raise DeclarativeActionError(f"HTTP request to '{url}' failed: {type(exc).__name__}") from exc
+
+        if result.is_success_status_code:
+            self._assign_response(state, result)
+            self._assign_response_headers(state, result)
+            self._append_response_to_conversation(state, conversation_id_expr, result.body)
+            await ctx.send_message(ActionComplete())
+            return
+
+        # Non-success path: still publish headers diagnostically, then raise.
+        self._assign_response_headers(state, result)
+        body_preview = _format_body_for_diagnostics(result.body)
+        if body_preview:
+            message = f"HTTP request to '{url}' failed with status code {result.status_code}. Body: '{body_preview}'"
+        else:
+            message = f"HTTP request to '{url}' failed with status code {result.status_code}."
+        raise DeclarativeActionError(message)
+
+    # ----- Field resolution ----------------------------------------------------
+
+    def _get_method(self, state: DeclarativeWorkflowState) -> str:
+        method = self._action_def.get("method")
+        evaluated = state.eval_if_expression(method) if method is not None else None
+        if not evaluated:
+            return "GET"
+        return str(evaluated).upper()
+
+    def _get_url(self, state: DeclarativeWorkflowState) -> str:
+        raw = self._action_def.get("url")
+        if raw is None:
+            raise ValueError("HttpRequestAction requires a 'url' field.")
+        evaluated = state.eval_if_expression(raw)
+        if not isinstance(evaluated, str) or not evaluated:
+            raise ValueError("HttpRequestAction 'url' evaluated to an empty value.")
+        return evaluated
+
+    def _get_headers(self, state: DeclarativeWorkflowState) -> dict[str, str] | None:
+        raw_headers = self._action_def.get("headers")
+        if not isinstance(raw_headers, Mapping) or not raw_headers:
+            return None
+        result: dict[str, str] = {}
+        for key, value in raw_headers.items():  # type: ignore[reportUnknownVariableType]
+            if not isinstance(key, str) or not key:
+                continue
+            evaluated = state.eval_if_expression(value)
+            if evaluated is None:
+                continue
+            text = str(evaluated)
+            if not text:
+                continue
+            result[key] = text
+        return result or None
+
+    def _get_query_parameters(self, state: DeclarativeWorkflowState) -> dict[str, str] | None:
+        raw_params = self._action_def.get("queryParameters")
+        if not isinstance(raw_params, Mapping) or not raw_params:
+            return None
+        result: dict[str, str] = {}
+        for key, value in raw_params.items():  # type: ignore[reportUnknownVariableType]
+            if not isinstance(key, str) or not key or value is None:
+                continue
+            evaluated = state.eval_if_expression(value)
+            formatted = _format_query_value(evaluated)
+            if formatted is not None:
+                result[key] = formatted
+        return result or None
+
+    def _get_body(self, state: DeclarativeWorkflowState) -> tuple[str | None, str | None]:
+        raw_body = self._action_def.get("body")
+        if raw_body is None:
+            return None, None
+        if not isinstance(raw_body, Mapping):
+            raise ValueError(
+                "HttpRequestAction 'body' must be a mapping with a 'kind' field (json, raw) or omitted entirely."
+            )
+
+        kind_value: Any = raw_body.get("kind") or raw_body.get("$kind")  # type: ignore[reportUnknownMemberType]
+        if kind_value is None:
+            raise ValueError(
+                "HttpRequestAction 'body' is missing 'kind'. Use 'json', 'raw', or omit 'body' for no request body."
+            )
+        if not isinstance(kind_value, str):
+            raise ValueError(f"HttpRequestAction 'body.kind' must be a string, got {kind_value!r}.")
+
+        if kind_value in _BODY_KIND_NONE:
+            return None, None
+
+        if kind_value in _BODY_KIND_JSON:
+            content_expr: Any = raw_body.get("content")  # type: ignore[reportUnknownMemberType]
+            if content_expr is None:
+                return None, None
+            evaluated = state.eval_if_expression(content_expr)
+            try:
+                body_text = json.dumps(evaluated, default=str)
+            except (TypeError, ValueError) as exc:
+                raise ValueError(f"HttpRequestAction 'body.content' could not be serialised as JSON: {exc}") from exc
+            return body_text, "application/json"
+
+        if kind_value in _BODY_KIND_RAW:
+            content_expr = raw_body.get("content")  # type: ignore[reportUnknownMemberType]
+            content_type_expr: Any = raw_body.get("contentType")  # type: ignore[reportUnknownMemberType]
+            content: str | None = None
+            if content_expr is not None:
+                evaluated = state.eval_if_expression(content_expr)
+                content = None if evaluated is None else str(evaluated)
+            content_type: str | None = None
+            if content_type_expr is not None:
+                ct_eval = state.eval_if_expression(content_type_expr)
+                ct_text = None if ct_eval is None else str(ct_eval)
+                content_type = ct_text or None
+            # Match .NET RawRequestContent semantics: when a raw body is sent
+            # without an explicit content type, default to text/plain so the
+            # request is interpretable by servers.
+            if content is not None and not content_type:
+                content_type = "text/plain"
+            return content, content_type
+
+        raise ValueError(
+            f"HttpRequestAction 'body.kind' has unsupported value '{kind_value}'. "
+            "Expected one of: json, raw, JsonRequestContent, RawRequestContent, "
+            "NoRequestContent."
+        )
+
+    def _get_timeout_ms(self, state: DeclarativeWorkflowState) -> int | None:
+        raw = self._action_def.get("requestTimeoutInMilliseconds")
+        if raw is None:
+            return None
+        evaluated = state.eval_if_expression(raw)
+        if evaluated is None:
+            return None
+        try:
+            value = int(evaluated)
+        except (TypeError, ValueError):
+            logger.debug(
+                "HttpRequestAction: ignoring non-numeric requestTimeoutInMilliseconds=%r",
+                evaluated,
+            )
+            return None
+        return value if value > 0 else None
+
+    def _get_connection_name(self, state: DeclarativeWorkflowState) -> str | None:
+        connection = self._action_def.get("connection")
+        if not isinstance(connection, Mapping):
+            return None
+        name_expr: Any = connection.get("name")  # type: ignore[reportUnknownMemberType]
+        if name_expr is None:
+            return None
+        evaluated = state.eval_if_expression(name_expr)
+        if evaluated is None:
+            return None
+        text = str(evaluated)
+        return text or None
+
+    # ----- Result handling -----------------------------------------------------
+
+    def _assign_response(self, state: DeclarativeWorkflowState, result: HttpRequestResult) -> None:
+        path = _get_path(self._action_def, "response")
+        if path is None:
+            return
+        state.set(path, _parse_response_body(result.body))
+
+    def _assign_response_headers(self, state: DeclarativeWorkflowState, result: HttpRequestResult) -> None:
+        path = _get_path(self._action_def, "responseHeaders")
+        if path is None:
+            return
+        if not result.headers:
+            state.set(path, None)
+            return
+        # Fold multi-value headers with commas (standard HTTP folding) only at
+        # assignment time. The raw multi-value dict on HttpRequestResult.headers
+        # is left untouched so callers/tests can inspect duplicates.
+        flattened: dict[str, str] = {}
+        for key, values in result.headers.items():
+            flattened[key] = ",".join(values)
+        state.set(path, flattened)
+
+    def _append_response_to_conversation(
+        self,
+        state: DeclarativeWorkflowState,
+        conversation_id_expr: str | None,
+        body: str,
+    ) -> None:
+        if not body:
+            return
+        messages_path = _get_messages_path(state, conversation_id_expr)
+        if messages_path is None:
+            return
+        # Mirrors InvokeAzureAgentExecutor: rely on state.append to lazily
+        # create the conversation entry. Avoids re-parsing the id back out
+        # of the dotted path string.
+        message = Message(role="assistant", contents=[body])
+        state.append(messages_path, message)
+
+
+HTTP_ACTION_EXECUTORS: dict[str, type[DeclarativeActionExecutor]] = {
+    "HttpRequestAction": HttpRequestActionExecutor,
+}

python/packages/declarative/agent_framework_declarative/_workflows/_factory.py

@@ -24,18 +24,16 @@ from agent_framework import (
     SupportsAgentRun,
     Workflow,
 )
-from agent_framework.exceptions import WorkflowException
 
 from .._loader import AgentFactory
 from ._declarative_builder import DeclarativeWorkflowBuilder
+from ._errors import DeclarativeWorkflowError
+from ._http_handler import HttpRequestHandler
 
 logger = logging.getLogger("agent_framework.declarative")
 
 
-class DeclarativeWorkflowError(WorkflowException):
-    """Exception raised for errors in declarative workflow processing."""
-
-    pass
+__all__ = ["WorkflowFactory"]
 
 
 class WorkflowFactory:
@@ -92,6 +90,7 @@ class WorkflowFactory:
         env_file: str | None = None,
         checkpoint_storage: CheckpointStorage | None = None,
         max_iterations: int | None = None,
+        http_request_handler: HttpRequestHandler | None = None,
     ) -> None:
         """Initialize the workflow factory.
 
@@ -105,6 +104,12 @@ class WorkflowFactory:
             max_iterations: Optional maximum runner supersteps.  Overrides the YAML ``maxTurns``
                 field and the core default (100).  Workflows with ``GotoAction`` loops (e.g.
                 DeepResearch) typically need a higher value.
+            http_request_handler: Optional handler used to dispatch HTTP requests for
+                ``HttpRequestAction``. Required if the workflow contains any
+                ``HttpRequestAction``; build will fail with :class:`DeclarativeWorkflowError`
+                otherwise. Use :class:`agent_framework.declarative.DefaultHttpRequestHandler`
+                for a no-policy ``httpx``-based default, or supply your own implementation
+                to enforce SSRF guards, allowlisting, or auth resolution.
 
         Examples:
             .. code-block:: python
@@ -144,6 +149,7 @@ class WorkflowFactory:
         self._tools: dict[str, Any] = {}  # Tool registry for InvokeFunctionTool actions
         self._checkpoint_storage = checkpoint_storage
         self._max_iterations = max_iterations
+        self._http_request_handler = http_request_handler
 
     def create_workflow_from_yaml_path(
         self,
@@ -387,6 +393,7 @@ class WorkflowFactory:
                 tools=self._tools,
                 checkpoint_storage=self._checkpoint_storage,
                 max_iterations=self._max_iterations,
+                http_request_handler=self._http_request_handler,
             )
             workflow = graph_builder.build()
         except ValueError as e:

python/packages/declarative/agent_framework_declarative/_workflows/_http_handler.py

@@ -0,0 +1,237 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""HTTP request handler abstraction for declarative workflows.
+
+Mirrors the .NET ``IHttpRequestHandler`` / ``DefaultHttpRequestHandler`` pair from
+``Microsoft.Agents.AI.Workflows.Declarative``. Provides:
+
+- :class:`HttpRequestInfo` — request input data passed from the executor.
+- :class:`HttpRequestResult` — response data returned to the executor.
+- :class:`HttpRequestHandler` — :class:`typing.Protocol` callers implement to plug
+  in custom transports (e.g. with allowlisting, mTLS, retries, etc.).
+- :class:`DefaultHttpRequestHandler` — production-grade default backed by
+  ``httpx.AsyncClient``.
+
+Security note: :class:`DefaultHttpRequestHandler` performs **no** URL filtering
+or SSRF protection. Production deployments should supply a custom handler that
+enforces an allowlist or DNS-rebinding-resistant policy. This split mirrors the
+.NET design.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+import httpx
+
+__all__ = [
+    "DefaultHttpRequestHandler",
+    "HttpRequestHandler",
+    "HttpRequestInfo",
+    "HttpRequestResult",
+]
+
+
+@dataclass
+class HttpRequestInfo:
+    """Description of an HTTP request to be dispatched by a :class:`HttpRequestHandler`.
+
+    Mirrors the .NET ``HttpRequestInfo`` record. Field semantics:
+
+    - ``method``: HTTP method (``GET``, ``POST``, etc.). Already upper-cased by the executor.
+    - ``url``: Absolute URL. Already evaluated from the YAML expression.
+    - ``headers``: Single-value header map (case-insensitive keys per HTTP semantics
+      but stored as authored). Empty values are skipped by the executor.
+    - ``query_parameters``: String key/value pairs appended to the URL.
+    - ``body``: Request body bytes/text, or ``None`` for no body.
+    - ``body_content_type``: Content type to send (e.g. ``application/json``).
+      Ignored when ``body`` is ``None``.
+    - ``timeout_ms``: Per-request timeout in milliseconds. ``None`` => use the
+      handler's default.
+    - ``connection_name``: Optional Foundry connection name for handlers that
+      resolve auth/credentials by connection.
+    """
+
+    method: str
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)  # type: ignore[reportUnknownVariableType]
+    query_parameters: dict[str, str] = field(default_factory=dict)  # type: ignore[reportUnknownVariableType]
+    body: str | None = None
+    body_content_type: str | None = None
+    timeout_ms: int | None = None
+    connection_name: str | None = None
+
+
+@dataclass
+class HttpRequestResult:
+    """Response returned by a :class:`HttpRequestHandler`.
+
+    Mirrors the .NET ``HttpRequestResult`` record. ``headers`` preserves
+    multi-value response headers (e.g. multiple ``Set-Cookie`` headers) as a
+    ``dict[str, list[str]]``. The executor folds duplicates into a single
+    comma-joined string only at the point it assigns ``responseHeaders`` to
+    workflow state.
+
+    Header keys are normalized to lowercase so that lookups are consistent
+    regardless of the server's transmitted casing (HTTP headers are
+    case-insensitive per RFC 7230 §3.2). Custom :class:`HttpRequestHandler`
+    implementations should follow the same convention.
+    """
+
+    status_code: int
+    is_success_status_code: bool
+    body: str
+    headers: dict[str, list[str]] = field(default_factory=dict)  # type: ignore[reportUnknownVariableType]
+
+
+@runtime_checkable
+class HttpRequestHandler(Protocol):
+    """Protocol for HTTP request handlers used by ``HttpRequestAction``.
+
+    Implementations must be safe to call concurrently from multiple workflow
+    runs. Implementations are responsible for any URL allowlisting, SSRF
+    guards, retry policies, auth resolution, and other policies that the
+    workflow author wants applied.
+    """
+
+    async def send(self, info: HttpRequestInfo) -> HttpRequestResult:
+        """Dispatch ``info`` and return the response result.
+
+        Args:
+            info: Description of the request to send.
+
+        Returns:
+            The response. Implementations should NOT raise on non-2xx status
+            codes; instead, set ``is_success_status_code`` accordingly. They
+            SHOULD raise on transport-level failures (connection refused,
+            DNS errors, timeouts).
+        """
+        ...
+
+
+ClientProvider = Callable[[HttpRequestInfo], Awaitable["httpx.AsyncClient | None"]]
+
+
+class DefaultHttpRequestHandler:
+    """Default :class:`HttpRequestHandler` backed by :class:`httpx.AsyncClient`.
+
+    Construction modes:
+
+    1. ``DefaultHttpRequestHandler()`` — owns an internal client created lazily
+       on first ``send()``. Closed by :meth:`aclose`.
+    2. ``DefaultHttpRequestHandler(client=existing)`` — caller-owned client.
+       Not closed by :meth:`aclose`.
+    3. ``DefaultHttpRequestHandler(client_provider=cb)`` — per-request client
+       lookup (parity with .NET's ``httpClientProvider`` callback). The
+       provider may return ``None`` to fall back to the owned/default client.
+
+    .. warning::
+
+       This handler performs **no** URL filtering or SSRF protection. Wrap or
+       replace it with a custom handler in production.
+    """
+
+    def __init__(
+        self,
+        *,
+        client: httpx.AsyncClient | None = None,
+        client_provider: ClientProvider | None = None,
+    ) -> None:
+        self._owned_client: httpx.AsyncClient | None = None
+        self._caller_client = client
+        self._client_provider = client_provider
+        # Guards lazy creation of ``_owned_client`` against concurrent first
+        # ``send()`` calls leaking duplicate clients.
+        self._owned_client_lock = asyncio.Lock()
+
+    async def send(self, info: HttpRequestInfo) -> HttpRequestResult:
+        """Dispatch the request and return the parsed result."""
+        if not info.url:
+            raise ValueError("HttpRequestInfo.url must be a non-empty string.")
+        if not info.method:
+            raise ValueError("HttpRequestInfo.method must be a non-empty string.")
+
+        client = await self._resolve_client(info)
+
+        timeout: httpx.Timeout | object
+        if info.timeout_ms is not None and info.timeout_ms > 0:
+            timeout = httpx.Timeout(info.timeout_ms / 1000.0)
+        else:
+            timeout = httpx.USE_CLIENT_DEFAULT
+
+        headers = dict(info.headers)
+        content: bytes | str | None = None
+        if info.body is not None:
+            content = info.body
+            if not _has_header(headers, "content-type"):
+                # Match .NET DefaultHttpRequestHandler: when a body is sent
+                # without an explicit content type, default to ``text/plain``
+                # so the request is interpretable by servers and direct
+                # callers (not just the YAML executor) get sensible defaults.
+                headers["Content-Type"] = info.body_content_type or "text/plain"
+
+        params: Mapping[str, str] | None = info.query_parameters or None
+
+        response = await client.request(
+            method=info.method,
+            url=info.url,
+            params=params,
+            headers=headers or None,
+            content=content,
+            timeout=timeout,  # type: ignore[arg-type]
+        )
+
+        # Preserve multi-value headers (e.g. multiple Set-Cookie) as list[str].
+        # Normalize names to lowercase so lookups are consistent and case
+        # variations from the transport do not create duplicate logical keys
+        # (HTTP headers are case-insensitive per RFC 7230 §3.2).
+        result_headers: dict[str, list[str]] = {}
+        for key, value in response.headers.multi_items():
+            result_headers.setdefault(key.lower(), []).append(value)
+
+        body_text = response.text
+
+        return HttpRequestResult(
+            status_code=response.status_code,
+            is_success_status_code=200 <= response.status_code < 300,
+            body=body_text,
+            headers=result_headers,
+        )
+
+    async def aclose(self) -> None:
+        """Release the owned client, if any. Caller-owned clients are NOT closed."""
+        if self._owned_client is not None:
+            await self._owned_client.aclose()
+            self._owned_client = None
+
+    async def _resolve_client(self, info: HttpRequestInfo) -> httpx.AsyncClient:
+        """Pick a client for this request: provider → caller → lazily-owned."""
+        if self._client_provider is not None:
+            provided = await self._client_provider(info)
+            if provided is not None:
+                return provided
+        if self._caller_client is not None:
+            return self._caller_client
+        if self._owned_client is None:
+            # Double-checked locking under asyncio.Lock so concurrent first
+            # callers don't each create a fresh httpx.AsyncClient and orphan
+            # one of them.
+            async with self._owned_client_lock:
+                if self._owned_client is None:
+                    self._owned_client = httpx.AsyncClient()
+        return self._owned_client
+
+    async def __aenter__(self) -> DefaultHttpRequestHandler:
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        await self.aclose()
+
+
+def _has_header(headers: Mapping[str, str], name: str) -> bool:
+    """Case-insensitive header presence check."""
+    needle = name.lower()
+    return any(key.lower() == needle for key in headers)