Python: bump package versions for 1.2.2 release (#5561)

* Python: bump package versions for 1.2.2 release

PATCH bump (1.2.1 -> 1.2.2) for the released cohort. Five PRs land in this
window:

- agent-framework-openai: fix file_search citations breaking the assistant-
  message history roundtrip (#5557) — drives the released-tier PATCH
- agent-framework-orchestrations: [BREAKING] standardize orchestration
  terminal outputs as AgentResponse (#5301)
- agent-framework-core, agent-framework-declarative: preserve Workflow.run()
  shared state across calls, accept list[Message] in declarative start
  executor, and coerce Enum values when serializing PowerFx symbols (#5531)
- agent-framework-foundry-hosting: add hosted Durable Workflow support
  (#5531)
- agent-framework-azure-contentunderstanding: new alpha package — Azure AI
  Content Understanding context provider (#4829)
- dependencies: workspace package dependency refresh (#5555)

Per lockstep convention, all 21 beta packages stamp 1.0.0b260429 and all 4
alpha packages (now including the new contentunderstanding) stamp
1.0.0a260429. Date stamp reflects 2026-04-29 Pacific. Every non-core package
floor on agent-framework-core is raised to >=1.2.2; the new
contentunderstanding package's stale >=1.0.0 floor is brought into line.

Two follow-on fixes bundled to keep validate-dependency-bounds-test green
at lowest-direct resolution:
- Bump agent-framework-azure-contentunderstanding's azure-ai-content
  understanding lower bound from >=1.0.0 to >=1.0.1 (1.0.0 ships without
  proper typing — pyright reports 65 unknown-type errors)
- Add pyright ignore comments to core/foundry/__init__.pyi for the new
  alpha package's type-stub imports, since alpha packages are not in
  core's [all] extra and therefore aren't installed at lowest-direct

* Python: add #5552 to 1.2.2 CHANGELOG

Add the streaming-span observability fix to the Fixed section. PR is on
upstream/main but not yet pulled into origin/main; the code itself will
land via the PR merge.

* Python: address PR #5561 review feedback on dependency bounds

Two packaging fixes flagged in review:

1. agent-framework-azure-contentunderstanding: add agent-framework-foundry
   as a runtime dependency. The package's README directs users to
   `pip install agent-framework-azure-contentunderstanding --pre` and the
   basic example imports `FoundryChatClient` from `agent_framework.foundry`,
   so the documented install path was failing with ImportError. Pulling
   agent-framework-foundry into deps makes the advertised entry path
   self-contained.

2. agent-framework-foundry: bump agent-framework-openai lower bound from
   >=1.1.0 to >=1.2.2,<2. Foundry imports private modules from
   agent_framework_openai (`_chat_client.py:22`, `_agent.py:34`), so
   resolvers were free to pair foundry==1.2.2 with older OpenAI versions
   that lack this release's coordinated Responses/history fix. Lockstep the
   floor with the released cohort to prevent mismatched installs.

Both changes pass `validate-dependency-bounds-test` lower + upper at
their respective packages.

.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/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/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/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/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/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/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/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/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

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/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/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/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/_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/pyproject.toml

@@ -4,7 +4,7 @@ description = "Declarative specification support 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",
     "powerfx>=0.0.32,<0.0.35; python_version < '3.14'",
     "pyyaml>=6.0,<7.0",
 ]

python/packages/declarative/tests/test_powerfx_safe.py

@@ -0,0 +1,59 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Regression tests for ``_make_powerfx_safe``.
+
+PowerFx (via pythonnet) only accepts plain primitives, dicts, and lists.
+``Enum`` instances - especially ``str``- and ``int``-subclass enums like
+MAF's ``MessageRole`` - silently pass ``isinstance(v, str)`` /
+``isinstance(v, int)`` checks but blow up later inside pythonnet with
+``'<EnumName>' value cannot be converted to System.<X>``. These tests
+pin down the Enum coercion branch so we don't regress that interop fix.
+"""
+
+from enum import Enum, IntEnum
+
+from agent_framework_declarative._workflows._declarative_base import _make_powerfx_safe
+
+
+class _StrRole(str, Enum):
+    USER = "user"
+    SYSTEM = "system"
+
+
+class _IntCode(IntEnum):
+    ONE = 1
+    TWO = 2
+
+
+class _PlainEnum(Enum):
+    X = "x"
+    Y = 42
+
+
+def test_str_subclass_enum_reduces_to_str():
+    assert _make_powerfx_safe(_StrRole.USER) == "user"
+    assert type(_make_powerfx_safe(_StrRole.USER)) is str
+
+
+def test_int_subclass_enum_reduces_to_int():
+    assert _make_powerfx_safe(_IntCode.ONE) == 1
+    assert type(_make_powerfx_safe(_IntCode.ONE)) is int
+
+
+def test_plain_enum_reduces_to_underlying_value():
+    assert _make_powerfx_safe(_PlainEnum.X) == "x"
+    assert _make_powerfx_safe(_PlainEnum.Y) == 42
+
+
+def test_enum_inside_dict_is_coerced():
+    safe = _make_powerfx_safe({"role": _StrRole.USER, "code": _IntCode.TWO})
+    assert safe == {"role": "user", "code": 2}
+    assert type(safe["role"]) is str
+    assert type(safe["code"]) is int
+
+
+def test_enum_inside_list_is_coerced():
+    safe = _make_powerfx_safe([_StrRole.USER, _IntCode.ONE])
+    assert safe == ["user", 1]
+    assert type(safe[0]) is str
+    assert type(safe[1]) is int

python/packages/declarative/tests/test_workflow_factory.py

@@ -228,6 +228,94 @@ actions:
         outputs = result.get_outputs()
         assert any("hello-world" in str(o) for o in outputs), f"Expected 'hello-world' in outputs but got: {outputs}"
 
+    async def test_as_agent_round_trip_with_last_message_text(self):
+        """Regression test: a declarative workflow built via WorkflowFactory must be
+        consumable as an AIAgent via Workflow.as_agent().
+
+        Specifically, the declarative start executor must accept list[Message]
+        (the input passed by WorkflowAgent) and populate System.LastMessageText
+        so =System.LastMessageText is resolvable in the YAML.
+        """
+        factory = WorkflowFactory()
+        workflow = factory.create_workflow_from_yaml("""
+name: as-agent-roundtrip-test
+actions:
+  - kind: SetVariable
+    variable: Local.echo
+    value: =System.LastMessageText
+  - kind: SendActivity
+    activity:
+      text: =Local.echo
+""")
+
+        agent = workflow.as_agent(name="echo-agent")
+        response = await agent.run("Hello there")
+
+        assert "Hello there" in response.text, (
+            f"Expected 'Hello there' in agent response text but got: {response.text!r}"
+        )
+
+    async def test_as_agent_continuation_preserves_prior_state(self):
+        """Regression test for the ``is_continuation`` branch in
+        ``DeclarativeWorkflowExecutor._ensure_state_initialized``.
+
+        Verifies, end-to-end via ``Workflow.as_agent()``:
+          * Turn 1 initializes the declarative state via ``state.initialize``.
+          * Turn 2 takes the *continuation* branch (skips ``state.initialize``),
+            so any non-Inputs/non-System state stamped on turn 1 survives.
+          * Turn 2 still refreshes ``Inputs.input`` and
+            ``System.LastMessage*`` to the new user message.
+
+        Without state preservation, ``Workflow.run`` would clear shared state
+        on entry and ``state.initialize`` would re-run on every turn,
+        wiping the marker we stamped between calls.
+        """
+        from agent_framework_declarative._workflows._declarative_base import DECLARATIVE_STATE_KEY
+
+        factory = WorkflowFactory()
+        workflow = factory.create_workflow_from_yaml("""
+name: as-agent-continuation-test
+actions:
+  - kind: SendActivity
+    activity:
+      text: =System.LastMessageText
+""")
+
+        agent = workflow.as_agent(name="continuation-agent")
+
+        first = await agent.run("turn-1-msg")
+        assert first.text == "turn-1-msg", f"Expected turn-1 echo 'turn-1-msg', got: {first.text!r}"
+
+        # Stamp a marker into the declarative state between turns. The
+        # continuation branch must preserve it; a state-clearing run would
+        # wipe ``DECLARATIVE_STATE_KEY`` and force re-initialization.
+        state_data = workflow._state.get(DECLARATIVE_STATE_KEY)
+        assert isinstance(state_data, dict), "Expected declarative state to be initialized after turn 1"
+        state_data["Local"] = {"persisted_marker": "kept-from-turn-1"}
+        workflow._state.set(DECLARATIVE_STATE_KEY, state_data)
+        workflow._state.commit()
+
+        second = await agent.run("turn-2-msg")
+        assert second.text == "turn-2-msg", (
+            f"Expected System.LastMessageText to refresh to 'turn-2-msg', got: {second.text!r}"
+        )
+
+        # The continuation branch in ``_ensure_state_initialized`` must:
+        # 1. preserve the cross-turn marker we stamped above
+        # 2. refresh Inputs.input and System.LastMessage* to the new turn
+        post_state = workflow._state.get(DECLARATIVE_STATE_KEY)
+        assert isinstance(post_state, dict), "declarative state vanished between turns"
+        local = post_state.get("Local", {})
+        assert local.get("persisted_marker") == "kept-from-turn-1", (
+            f"Cross-turn marker was wiped (state was reset). post_state Local={local!r}"
+        )
+        assert post_state.get("Inputs", {}).get("input") == "turn-2-msg", (
+            f"Inputs.input not refreshed on turn 2: {post_state.get('Inputs')!r}"
+        )
+        assert post_state.get("System", {}).get("LastMessageText") == "turn-2-msg", (
+            f"System.LastMessageText not refreshed on turn 2: {post_state.get('System')!r}"
+        )
+
 
 class TestWorkflowFactoryAgentRegistration:
     """Tests for agent registration."""

python/packages/devui/pyproject.toml

@@ -4,7 +4,7 @@ description = "Debug UI for Microsoft Agent Framework with OpenAI-compatible API
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260428"
+version = "1.0.0b260429"
 license-files = ["LICENSE"]
 urls.homepage = "https://github.com/microsoft/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",
      "openai>=1.99.0,<3",
      "opentelemetry-sdk>=1.39.0,<2",
      "fastapi>=0.115.0,<0.133.1",

python/packages/durabletask/pyproject.toml

@@ -4,7 +4,7 @@ description = "Durable Task 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",
     "durabletask>=1.3.0,<2",
     "durabletask-azuremanaged>=1.3.0,<2",
     "python-dateutil>=2.8.0,<3",

python/packages/foundry/pyproject.toml

@@ -4,7 +4,7 @@ description = "Microsoft Foundry integrations for Microsoft Agent Framework."
 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"
@@ -23,8 +23,8 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
-    "agent-framework-openai>=1.1.0,<2",
+    "agent-framework-core>=1.2.2,<2",
+    "agent-framework-openai>=1.2.2,<2",
     "azure-ai-inference>=1.0.0b9,<1.0.0b10",
     "azure-ai-projects>=2.1.0,<3.0",
 ]

python/packages/foundry/tests/foundry/test_foundry_embedding_client.py

@@ -303,6 +303,7 @@ skip_if_foundry_inference_integration_tests_disabled = pytest.mark.skipif(
 class TestFoundryEmbeddingIntegration:
     """Integration tests requiring a live Foundry inference endpoint."""
 
+    @pytest.mark.skip(reason="Flaky in merge queue, blocking unrelated PRs. Tracked in #5553.")
     @pytest.mark.flaky
     @pytest.mark.integration
     @skip_if_foundry_inference_integration_tests_disabled

python/packages/foundry_hosting/agent_framework_foundry_hosting/_responses.py

@@ -272,50 +272,86 @@ class ResponsesHostServer(ResponsesAgentServerHost):
         if not isinstance(self._agent, WorkflowAgent):
             raise RuntimeError("Agent is not a workflow agent.")
 
-        # Restore from the latest checkpoint if available, otherwise start with an empty history
+        # Determine the latest checkpoint (if any) so we can resume the
+        # workflow's prior state for this turn. The directory is keyed by
+        # the inbound context id (conversation_id when set, otherwise
+        # previous_response_id). Multi-turn declarative workflows need the
+        # workflow's internal state (e.g. Conversation.messages,
+        # intermediate Local.* variables) to survive across user turns;
+        # the only place that state lives is the workflow checkpoint, so
+        # on every turn we restore the latest checkpoint and feed the new
+        # input back into the start executor as a continuation rather than
+        # a fresh run.
+        latest_checkpoint_id: str | None = None
+        restore_storage: FileCheckpointStorage | None = None
         if context_id is not None:
-            checkpoint_storage = FileCheckpointStorage(os.path.join(self._checkpoint_storage_path, context_id))
-            latest_checkpoint = await checkpoint_storage.get_latest(workflow_name=self._agent.workflow.name)
+            restore_storage = FileCheckpointStorage(os.path.join(self._checkpoint_storage_path, context_id))
+            latest_checkpoint = await restore_storage.get_latest(workflow_name=self._agent.workflow.name)
             if latest_checkpoint is not None:
-                if not is_streaming_request:
-                    _ = await self._agent.run(
-                        stream=False,
-                        checkpoint_id=latest_checkpoint.checkpoint_id,
-                        checkpoint_storage=checkpoint_storage,
-                    )
-                else:
-                    # Consume the streaming or the invocation will result in a no-op
-                    async for _ in self._agent.run(
-                        stream=True,
-                        checkpoint_id=latest_checkpoint.checkpoint_id,
-                        checkpoint_storage=checkpoint_storage,
-                    ):
-                        pass
+                latest_checkpoint_id = latest_checkpoint.checkpoint_id
+
+        # Storage that will receive checkpoints written during this turn.
+        # When the caller chains with previous_response_id, the next turn
+        # will reference the current response_id as its previous_response_id,
+        # so new checkpoints must land under the current response_id (or the
+        # conversation_id when set). When conversation_id is set, this
+        # matches restore_storage; when only previous_response_id was
+        # supplied, restore_storage points at the *prior* response's
+        # directory and write_storage points at the *current* response's.
+        write_context_id = context.conversation_id or context.response_id
+        write_storage = FileCheckpointStorage(os.path.join(self._checkpoint_storage_path, write_context_id))
+
+        # Multi-turn pattern: when we have a prior checkpoint, restore it
+        # first (drive the workflow back to idle with prior state intact),
+        # then make a separate call that delivers the new user input. This
+        # depends on Workflow.run preserving shared state across calls. The
+        # restore-only call may yield events from any pending in-flight
+        # work in the checkpoint; we consume those internally here so they
+        # don't surface to the response stream as duplicates.
+        #
+        # If the restored checkpoint had pending request_info events, the
+        # restore-only call replays them through
+        # ``WorkflowAgent._convert_workflow_event_to_agent_response_updates``
+        # and populates ``self._agent.pending_requests``. That is the correct
+        # state: those requests are genuinely outstanding, and the next
+        # ``run(input_messages, ...)`` call may contain ``function_call_output``
+        # items (carried as FunctionResult/FunctionApprovalResponse content)
+        # that fulfill them via :meth:`WorkflowAgent._process_pending_requests`.
+        if latest_checkpoint_id is not None:
+            if is_streaming_request:
+                async for _ in self._agent.run(
+                    stream=True,
+                    checkpoint_id=latest_checkpoint_id,
+                    checkpoint_storage=restore_storage,
+                ):
+                    pass
+            else:
+                await self._agent.run(
+                    stream=False,
+                    checkpoint_id=latest_checkpoint_id,
+                    checkpoint_storage=restore_storage,
+                )
 
         # Now run the agent with the latest input
         response_event_stream = ResponseEventStream(response_id=context.response_id, model=request.model)
 
-        # Create a new checkpoint storage for this response based on the following rules:
-        # - If no previous response ID or conversation ID is provided,
-        #   create a new checkpoint storage for this response
-        # - If a previous response ID is provided, create a new checkpoint storage for this response
-        # - If a conversation ID is provided, reuse the existing checkpoint storage for the conversation
-        context_id = context.conversation_id or context.response_id
-        checkpoint_storage = FileCheckpointStorage(os.path.join(self._checkpoint_storage_path, context_id))
-
         yield response_event_stream.emit_created()
         yield response_event_stream.emit_in_progress()
 
         if not is_streaming_request:
-            # Run the agent in non-streaming mode
-            response = await self._agent.run(input_messages, stream=False, checkpoint_storage=checkpoint_storage)
+            # Run the agent in non-streaming mode with the new user input.
+            response = await self._agent.run(
+                input_messages,
+                stream=False,
+                checkpoint_storage=write_storage,
+            )
 
             for message in response.messages:
                 for content in message.contents:
                     async for item in _to_outputs(response_event_stream, content):
                         yield item
 
-            await self._delete_not_latest_checkpoints(checkpoint_storage, self._agent.workflow.name)
+            await self._delete_not_latest_checkpoints(write_storage, self._agent.workflow.name)
             yield response_event_stream.emit_completed()
             return
 
@@ -323,8 +359,12 @@ class ResponsesHostServer(ResponsesAgentServerHost):
         # lazily created on matching content, closed when a different type arrives.
         tracker = _OutputItemTracker(response_event_stream)
 
-        # Run the workflow agent in streaming mode
-        async for update in self._agent.run(input_messages, stream=True, checkpoint_storage=checkpoint_storage):
+        # Run the workflow agent in streaming mode with the new user input.
+        async for update in self._agent.run(
+            input_messages,
+            stream=True,
+            checkpoint_storage=write_storage,
+        ):
             for content in update.contents:
                 for event in tracker.handle(content):
                     yield event
@@ -337,7 +377,7 @@ class ResponsesHostServer(ResponsesAgentServerHost):
         for event in tracker.close():
             yield event
 
-        await self._delete_not_latest_checkpoints(checkpoint_storage, self._agent.workflow.name)
+        await self._delete_not_latest_checkpoints(write_storage, self._agent.workflow.name)
         yield response_event_stream.emit_completed()
 
     @staticmethod

python/packages/foundry_hosting/pyproject.toml

@@ -4,7 +4,7 @@ description = "Foundry Hosting integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0a260428"
+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"
@@ -23,10 +23,10 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
-    "azure-ai-agentserver-core==2.0.0b3",
-    "azure-ai-agentserver-responses==1.0.0b5",
-    "azure-ai-agentserver-invocations==1.0.0b3",
+    "agent-framework-core>=1.2.2,<2",
+    "azure-ai-agentserver-core>=2.0.0b3,<3",
+    "azure-ai-agentserver-responses>=1.0.0b5,<2",
+    "azure-ai-agentserver-invocations>=1.0.0b3,<2",
 ]
 
 [tool.uv]

python/packages/foundry_hosting/tests/test_responses_int.py

@@ -559,6 +559,7 @@ class TestToolCalling:
 class TestOptions:
     """Verify chat options are passed through to the model."""
 
+    @pytest.mark.skip(reason="Flaky in merge queue, blocking unrelated PRs. Tracked in #5553.")
     @pytest.mark.flaky
     @pytest.mark.integration
     @skip_if_foundry_hosting_integration_tests_disabled

python/packages/foundry_local/pyproject.toml

@@ -4,7 +4,7 @@ description = "Foundry Local 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",
     "agent-framework-openai>=1.1.0,<2",
     "foundry-local-sdk>=0.5.1,<0.5.2",
 ]

python/packages/gemini/pyproject.toml

@@ -4,7 +4,7 @@ description = "Google Gemini integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0a260428"
+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"
@@ -24,7 +24,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2.0",
+    "agent-framework-core>=1.2.2,<2.0",
     "google-genai>=1.65.0,<2.0.0",
 ]
 

python/packages/github_copilot/pyproject.toml

@@ -4,7 +4,7 @@ description = "GitHub Copilot 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",
     "github-copilot-sdk>=0.2.1,<=0.2.1; python_version >= '3.11'",
 ]
 

python/packages/hyperlight/pyproject.toml

@@ -4,7 +4,7 @@ description = "Hyperlight CodeAct integrations for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0a260428"
+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"
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "hyperlight-sandbox>=0.3.0,<0.4",
     "hyperlight-sandbox-backend-wasm>=0.3.0,<0.4 ; ((sys_platform == 'linux' and platform_machine == 'x86_64') or (sys_platform == 'win32' and platform_machine == 'AMD64')) and python_version < '3.14'",
     "hyperlight-sandbox-python-guest>=0.3.0,<0.4",

python/packages/lab/pyproject.toml

@@ -4,7 +4,7 @@ description = "Experimental modules for Microsoft Agent Framework"
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.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 = [
   "Programming Language :: Python :: 3.14",
 ]
 dependencies = [
-  "agent-framework-core>=1.2.1,<2",
+  "agent-framework-core>=1.2.2,<2",
 ]
 
 [project.optional-dependencies]

python/packages/mem0/pyproject.toml

@@ -4,7 +4,7 @@ description = "Mem0 integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.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",
     "mem0ai>=1.0.0,<2",
 ]
 

python/packages/ollama/pyproject.toml

@@ -4,7 +4,7 @@ description = "Ollama 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://learn.microsoft.com/en-us/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",
     "ollama>=0.5.3,<0.5.4",
 ]
 

python/packages/openai/agent_framework_openai/_chat_client.py

@@ -241,6 +241,85 @@ OpenAIChatOptionsT = TypeVar(
 # endregion
 
 
+# region Helpers
+
+
+def _annotations_to_output_text(annotations: Sequence[Annotation] | None) -> list[dict[str, Any]]:
+    """Convert framework `Annotation` objects to Responses API `output_text` annotation dicts.
+
+    Citations from `file_search`, `code_interpreter` file paths, and url citations all collapse
+    to `Annotation(type="citation", ...)` in the framework. The original API form is recovered
+    here so assistant messages roundtrip cleanly through history forwarding.
+
+    Each Responses API annotation dict carries at most one `start_index`/`end_index` pair, so an
+    `Annotation` with multiple `annotated_regions` is fanned out into one entry per region.
+    Regions missing valid integer span bounds are skipped.
+    """
+    if not annotations:
+        return []
+    out: list[dict[str, Any]] = []
+    for annotation in annotations:
+        if annotation.get("type") != "citation":
+            continue
+        props = annotation.get("additional_properties") or {}
+        regions = annotation.get("annotated_regions") or []
+        file_id = annotation.get("file_id")
+        url = annotation.get("url")
+        title = annotation.get("title")
+        container_id = props.get("container_id")
+
+        if container_id and file_id:
+            for region in regions:
+                start = region.get("start_index")
+                end = region.get("end_index")
+                if not (isinstance(start, int) and isinstance(end, int)):
+                    continue
+                entry: dict[str, Any] = {
+                    "type": "container_file_citation",
+                    "container_id": container_id,
+                    "file_id": file_id,
+                    "start_index": start,
+                    "end_index": end,
+                }
+                if url:
+                    entry["filename"] = url
+                out.append(entry)
+        elif url and not file_id and regions:
+            for region in regions:
+                start = region.get("start_index")
+                end = region.get("end_index")
+                if not (isinstance(start, int) and isinstance(end, int)):
+                    continue
+                out.append({
+                    "type": "url_citation",
+                    "url": url,
+                    "title": title or "",
+                    "start_index": start,
+                    "end_index": end,
+                })
+        elif file_id and url:
+            entry = {
+                "type": "file_citation",
+                "file_id": file_id,
+                "filename": url,
+            }
+            if (idx := props.get("index")) is not None:
+                entry["index"] = idx
+            out.append(entry)
+        elif file_id:
+            entry = {
+                "type": "file_path",
+                "file_id": file_id,
+            }
+            if (idx := props.get("index")) is not None:
+                entry["index"] = idx
+            out.append(entry)
+    return out
+
+
+# endregion
+
+
 # region ResponsesClient
 
 
@@ -1374,7 +1453,7 @@ class RawOpenAIChatClient(  # type: ignore[misc]
                     return {
                         "type": "output_text",
                         "text": content.text,
-                        "annotations": [],
+                        "annotations": _annotations_to_output_text(getattr(content, "annotations", None)),
                     }
                 return {
                     "type": "input_text",
@@ -1522,6 +1601,13 @@ class RawOpenAIChatClient(  # type: ignore[misc]
                     "approve": content.approved,
                 }
             case "hosted_file":
+                # `input_file` is an input-only content type in the Responses API and is rejected
+                # inside an assistant message. Hosted-file content on an assistant message
+                # represents a citation produced by a hosted tool (e.g., file_search) and cannot be
+                # meaningfully replayed as input — drop it. The accompanying text annotations carry
+                # the citation context for round-tripping.
+                if role == "assistant":
+                    return {}
                 return {
                     "type": "input_file",
                     "file_id": content.file_id,
@@ -2502,45 +2588,63 @@ class RawOpenAIChatClient(  # type: ignore[misc]
 
                 ann_type = _get_ann_value("type")
                 ann_file_id = _get_ann_value("file_id")
+                # Hosted-file citations attach as text annotations (matching the non-streaming path)
+                # so they don't roundtrip as standalone `input_file` items in assistant history.
                 if ann_type == "file_path":
                     if ann_file_id:
+                        annotation_obj = Annotation(
+                            type="citation",
+                            file_id=str(ann_file_id),
+                            additional_properties={
+                                "annotation_index": event.annotation_index,
+                                "index": _get_ann_value("index"),
+                            },
+                            raw_representation=annotation,
+                        )
                         contents.append(
-                            Content.from_hosted_file(
-                                file_id=str(ann_file_id),
-                                additional_properties={
-                                    "annotation_index": event.annotation_index,
-                                    "index": _get_ann_value("index"),
-                                },
-                                raw_representation=event,
-                            )
+                            Content.from_text(text="", annotations=[annotation_obj], raw_representation=event)
                         )
                 elif ann_type == "file_citation":
                     if ann_file_id:
+                        ann_filename = _get_ann_value("filename")
+                        annotation_obj = Annotation(
+                            type="citation",
+                            file_id=str(ann_file_id),
+                            url=ann_filename,
+                            additional_properties={
+                                "annotation_index": event.annotation_index,
+                                "index": _get_ann_value("index"),
+                            },
+                            raw_representation=annotation,
+                        )
                         contents.append(
-                            Content.from_hosted_file(
-                                file_id=str(ann_file_id),
-                                additional_properties={
-                                    "annotation_index": event.annotation_index,
-                                    "filename": _get_ann_value("filename"),
-                                    "index": _get_ann_value("index"),
-                                },
-                                raw_representation=event,
-                            )
+                            Content.from_text(text="", annotations=[annotation_obj], raw_representation=event)
                         )
                 elif ann_type == "container_file_citation":
                     if ann_file_id:
+                        ann_filename = _get_ann_value("filename")
+                        ann_start = _get_ann_value("start_index")
+                        ann_end = _get_ann_value("end_index")
+                        annotation_obj = Annotation(
+                            type="citation",
+                            file_id=str(ann_file_id),
+                            url=ann_filename,
+                            additional_properties={
+                                "annotation_index": event.annotation_index,
+                                "container_id": _get_ann_value("container_id"),
+                            },
+                            raw_representation=annotation,
+                        )
+                        if ann_start is not None and ann_end is not None:
+                            annotation_obj["annotated_regions"] = [
+                                TextSpanRegion(
+                                    type="text_span",
+                                    start_index=ann_start,
+                                    end_index=ann_end,
+                                )
+                            ]
                         contents.append(
-                            Content.from_hosted_file(
-                                file_id=str(ann_file_id),
-                                additional_properties={
-                                    "annotation_index": event.annotation_index,
-                                    "container_id": _get_ann_value("container_id"),
-                                    "filename": _get_ann_value("filename"),
-                                    "start_index": _get_ann_value("start_index"),
-                                    "end_index": _get_ann_value("end_index"),
-                                },
-                                raw_representation=event,
-                            )
+                            Content.from_text(text="", annotations=[annotation_obj], raw_representation=event)
                         )
                 elif ann_type == "url_citation":
                     ann_url = _get_ann_value("url")

python/packages/openai/pyproject.toml

@@ -4,7 +4,7 @@ description = "OpenAI integrations for Microsoft Agent Framework."
 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"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.2.1,<2",
+    "agent-framework-core>=1.2.2,<2",
     "openai>=1.99.0,<3",
 ]
 

python/packages/openai/tests/openai/test_openai_chat_client.py

@@ -1914,6 +1914,285 @@ def test_hosted_file_content_preparation() -> None:
     assert result["file_id"] == "file_abc123"
 
 
+def test_assistant_text_preserves_citation_annotations_on_roundtrip() -> None:
+    """Citation annotations on assistant text should survive serialization back to the Responses API.
+
+    Previously `output_text.annotations` was hardcoded to `[]`, silently dropping `file_search`
+    citation context on every roundtrip. Preserving them keeps citations intact across
+    multi-agent forwarding.
+    """
+    from agent_framework._types import Annotation, TextSpanRegion
+
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+
+    text_content = Content.from_text(
+        "Per the docs, the answer is X. See also the report.",
+        annotations=[
+            Annotation(
+                type="citation",
+                file_id="file-abc123",
+                url="guidelines.md",
+                additional_properties={"index": 12},
+            ),
+            Annotation(
+                type="citation",
+                title="Quarterly Report",
+                url="https://example.com/report",
+                annotated_regions=[TextSpanRegion(type="text_span", start_index=40, end_index=46)],
+            ),
+            Annotation(
+                type="citation",
+                file_id="file-container456",
+                url="data.csv",
+                additional_properties={"container_id": "container-789"},
+                annotated_regions=[TextSpanRegion(type="text_span", start_index=0, end_index=3)],
+            ),
+        ],
+    )
+
+    result = client._prepare_content_for_openai("assistant", text_content)
+
+    assert result["type"] == "output_text"
+    annotations = result["annotations"]
+    assert len(annotations) == 3
+
+    file_citation = next(a for a in annotations if a["type"] == "file_citation")
+    assert file_citation["file_id"] == "file-abc123"
+    assert file_citation["filename"] == "guidelines.md"
+    assert file_citation["index"] == 12
+
+    url_citation = next(a for a in annotations if a["type"] == "url_citation")
+    assert url_citation["url"] == "https://example.com/report"
+    assert url_citation["title"] == "Quarterly Report"
+    assert url_citation["start_index"] == 40
+    assert url_citation["end_index"] == 46
+
+    container = next(a for a in annotations if a["type"] == "container_file_citation")
+    assert container["file_id"] == "file-container456"
+    assert container["container_id"] == "container-789"
+    assert container["filename"] == "data.csv"
+    assert container["start_index"] == 0
+    assert container["end_index"] == 3
+
+
+def test_assistant_text_preserves_file_path_annotation() -> None:
+    """A `file_path`-style citation (file_id only, no url) should serialize as `file_path`."""
+    from agent_framework._types import Annotation
+
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+
+    text_content = Content.from_text(
+        "See attached.",
+        annotations=[
+            Annotation(
+                type="citation",
+                file_id="file-only",
+                additional_properties={"index": 42},
+            ),
+        ],
+    )
+
+    result = client._prepare_content_for_openai("assistant", text_content)
+
+    assert result["type"] == "output_text"
+    annotations = result["annotations"]
+    assert annotations == [{"type": "file_path", "file_id": "file-only", "index": 42}]
+
+
+def test_assistant_text_fans_out_multiple_annotated_regions() -> None:
+    """A url_citation with multiple `annotated_regions` should emit one entry per region.
+
+    The Responses API annotation dict carries one start/end pair, so a framework Annotation
+    with N regions must produce N output annotation entries.
+    """
+    from agent_framework._types import Annotation, TextSpanRegion
+
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+
+    text_content = Content.from_text(
+        "See report. The report says X. Also report.",
+        annotations=[
+            Annotation(
+                type="citation",
+                title="Report",
+                url="https://example.com/report",
+                annotated_regions=[
+                    TextSpanRegion(type="text_span", start_index=4, end_index=10),
+                    TextSpanRegion(type="text_span", start_index=16, end_index=22),
+                    TextSpanRegion(type="text_span", start_index=36, end_index=42),
+                ],
+            ),
+        ],
+    )
+
+    result = client._prepare_content_for_openai("assistant", text_content)
+    annotations = result["annotations"]
+    assert len(annotations) == 3
+    assert all(a["type"] == "url_citation" for a in annotations)
+    spans = [(a["start_index"], a["end_index"]) for a in annotations]
+    assert spans == [(4, 10), (16, 22), (36, 42)]
+
+
+def test_assistant_text_skips_regions_with_invalid_span() -> None:
+    """Regions missing integer start/end bounds are skipped rather than emitted with `None`."""
+    from agent_framework._types import Annotation, TextSpanRegion
+
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+
+    text_content = Content.from_text(
+        "See report.",
+        annotations=[
+            Annotation(
+                type="citation",
+                title="Report",
+                url="https://example.com/report",
+                annotated_regions=[
+                    TextSpanRegion(type="text_span"),  # type: ignore[typeddict-item]
+                    TextSpanRegion(type="text_span", start_index=4, end_index=10),
+                ],
+            ),
+        ],
+    )
+
+    result = client._prepare_content_for_openai("assistant", text_content)
+    annotations = result["annotations"]
+    assert len(annotations) == 1
+    assert annotations[0]["start_index"] == 4
+    assert annotations[0]["end_index"] == 10
+
+
+def test_assistant_text_without_annotations_emits_empty_list() -> None:
+    """Plain assistant text should still emit `annotations: []` (Azure validation requires the field)."""
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+
+    result = client._prepare_content_for_openai("assistant", Content.from_text("hello"))
+
+    assert result["type"] == "output_text"
+    assert result["text"] == "hello"
+    assert result["annotations"] == []
+
+
+def test_streamed_file_citation_coalesces_onto_surrounding_text() -> None:
+    """Streamed citation events emit empty-text Content with annotations; `_finalize_response`
+    coalesces consecutive text contents and unions their annotations, so the citation lands on
+    the merged assistant text content (not a stray empty-text entry).
+
+    Without this, span indices in the annotation would reference `text == ""` after roundtrip.
+    """
+    text_event = MagicMock()
+    text_event.type = "response.output_text.delta"
+    text_event.delta = "Hello world."
+    text_event.item_id = "item_1"
+    text_event.output_index = 0
+    text_event.content_index = 0
+
+    citation_event = MagicMock()
+    citation_event.type = "response.output_text.annotation.added"
+    citation_event.annotation_index = 0
+    citation_event.annotation = {
+        "type": "file_citation",
+        "file_id": "file-abc",
+        "filename": "guidelines.md",
+        "index": 5,
+    }
+
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+    chat_options = ChatOptions()
+    function_call_ids: dict[int, tuple[str, str]] = {}
+
+    update1 = client._parse_chunk_from_openai(text_event, chat_options, function_call_ids)
+    update2 = client._parse_chunk_from_openai(citation_event, chat_options, function_call_ids)
+
+    response = ChatResponse.from_updates([update1, update2])
+
+    assert len(response.messages) == 1
+    contents = response.messages[0].contents
+    assert len(contents) == 1
+    merged = contents[0]
+    assert merged.type == "text"
+    assert merged.text == "Hello world."
+    assert merged.annotations is not None
+    assert len(merged.annotations) == 1
+    assert merged.annotations[0]["file_id"] == "file-abc"
+
+
+def test_streamed_file_citation_roundtrips_as_assistant_history() -> None:
+    """End-to-end: file_citation arrives via streaming, then gets forwarded as assistant history.
+
+    Reproduces the user-reported sequential/group-chat workflow bug where one agent's
+    `file_search` citations became `input_file` items in the next agent's request and were
+    rejected by the Responses API.
+    """
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+    chat_options = ChatOptions()
+    function_call_ids: dict[int, tuple[str, str]] = {}
+
+    text_event = MagicMock()
+    text_event.type = "response.output_text.delta"
+    text_event.delta = "According to the docs, the answer is X."
+    text_event.item_id = "item_1"
+    text_event.output_index = 0
+    text_event.content_index = 0
+
+    citation_event = MagicMock()
+    citation_event.type = "response.output_text.annotation.added"
+    citation_event.annotation_index = 0
+    citation_event.annotation = {
+        "type": "file_citation",
+        "file_id": "file-xyz789",
+        "filename": "guidelines.md",
+        "index": 12,
+    }
+
+    update1 = client._parse_chunk_from_openai(text_event, chat_options, function_call_ids)
+    update2 = client._parse_chunk_from_openai(citation_event, chat_options, function_call_ids)
+
+    assistant_history = Message(
+        role="assistant",
+        contents=[*update1.contents, *update2.contents],
+    )
+    prepared = client._prepare_message_for_openai(assistant_history)
+
+    assert len(prepared) == 1
+    content_items = prepared[0].get("content", [])
+    types = [c.get("type") for c in content_items]
+    assert "input_file" not in types, f"input_file leaked into assistant history: {types}"
+    output_text_items = [c for c in content_items if c.get("type") == "output_text"]
+    assert any(
+        any(a.get("type") == "file_citation" and a.get("file_id") == "file-xyz789" for a in c.get("annotations", []))
+        for c in output_text_items
+    ), "file_citation annotation should survive the streaming → history roundtrip"
+
+
+def test_hosted_file_in_assistant_message_does_not_emit_input_file() -> None:
+    """Hosted file citations attached to an assistant message must not roundtrip as `input_file`.
+
+    The Responses API rejects `input_file` items inside an assistant role's content array;
+    `input_file` is an input-only content type. This guards the multi-agent / sequential workflow
+    case where one agent's `file_search` citations get forwarded as history to the next call.
+    """
+    client = OpenAIChatClient(model="test-model", api_key="test-key")
+
+    assistant_msg = Message(
+        role="assistant",
+        contents=[
+            Content.from_text("According to the docs, the answer is X."),
+            Content.from_hosted_file(file_id="file_abc123"),
+        ],
+    )
+
+    prepared = client._prepare_message_for_openai(assistant_msg)
+
+    assert len(prepared) == 1
+    assistant_item = prepared[0]
+    assert assistant_item["role"] == "assistant"
+    content_types = [c.get("type") for c in assistant_item.get("content", [])]
+    assert "input_file" not in content_types, (
+        f"`input_file` is not valid inside an assistant message; got {content_types}"
+    )
+    assert "output_text" in content_types
+
+
 def test_function_approval_response_with_mcp_tool_call() -> None:
     """Test function approval response content with MCP server tool call content."""
     client = OpenAIChatClient(model="test-model", api_key="test-key")
@@ -2682,7 +2961,7 @@ def test_streaming_response_in_progress_type() -> None:
 
 
 def test_streaming_annotation_added_with_file_path() -> None:
-    """Test streaming annotation added event with file_path type extracts HostedFileContent."""
+    """Streaming `file_path` should attach as a text annotation, matching non-streaming."""
     client = OpenAIChatClient(model="test-model", api_key="test-key")
     chat_options = ChatOptions()
     function_call_ids: dict[int, tuple[str, str]] = {}
@@ -2700,15 +2979,23 @@ def test_streaming_annotation_added_with_file_path() -> None:
 
     assert len(response.contents) == 1
     content = response.contents[0]
-    assert content.type == "hosted_file"
-    assert content.file_id == "file-abc123"
-    assert content.additional_properties is not None
-    assert content.additional_properties.get("annotation_index") == 0
-    assert content.additional_properties.get("index") == 42
+    assert content.type == "text"
+    assert content.annotations is not None
+    assert len(content.annotations) == 1
+    annotation = content.annotations[0]
+    assert annotation["type"] == "citation"
+    assert annotation["file_id"] == "file-abc123"
+    assert annotation["additional_properties"]["annotation_index"] == 0
+    assert annotation["additional_properties"]["index"] == 42
 
 
 def test_streaming_annotation_added_with_file_citation() -> None:
-    """Test streaming annotation added event with file_citation type extracts HostedFileContent."""
+    """Streaming `file_citation` should attach as a text annotation, matching non-streaming.
+
+    Previously the streaming path produced a standalone `HostedFileContent`, which then
+    serialized as `input_file` in assistant history and was rejected by the Responses API.
+    Annotations on text content roundtrip cleanly.
+    """
     client = OpenAIChatClient(model="test-model", api_key="test-key")
     chat_options = ChatOptions()
     function_call_ids: dict[int, tuple[str, str]] = {}
@@ -2727,15 +3014,19 @@ def test_streaming_annotation_added_with_file_citation() -> None:
 
     assert len(response.contents) == 1
     content = response.contents[0]
-    assert content.type == "hosted_file"
-    assert content.file_id == "file-xyz789"
-    assert content.additional_properties is not None
-    assert content.additional_properties.get("filename") == "sample.txt"
-    assert content.additional_properties.get("index") == 15
+    assert content.type == "text"
+    assert content.annotations is not None
+    assert len(content.annotations) == 1
+    annotation = content.annotations[0]
+    assert annotation["type"] == "citation"
+    assert annotation["file_id"] == "file-xyz789"
+    assert annotation["url"] == "sample.txt"
+    assert annotation["additional_properties"]["annotation_index"] == 1
+    assert annotation["additional_properties"]["index"] == 15
 
 
 def test_streaming_annotation_added_with_container_file_citation() -> None:
-    """Test streaming annotation added event with container_file_citation type."""
+    """Streaming `container_file_citation` should attach as a text annotation."""
     client = OpenAIChatClient(model="test-model", api_key="test-key")
     chat_options = ChatOptions()
     function_call_ids: dict[int, tuple[str, str]] = {}
@@ -2756,13 +3047,19 @@ def test_streaming_annotation_added_with_container_file_citation() -> None:
 
     assert len(response.contents) == 1
     content = response.contents[0]
-    assert content.type == "hosted_file"
-    assert content.file_id == "file-container123"
-    assert content.additional_properties is not None
-    assert content.additional_properties.get("container_id") == "container-456"
-    assert content.additional_properties.get("filename") == "data.csv"
-    assert content.additional_properties.get("start_index") == 10
-    assert content.additional_properties.get("end_index") == 50
+    assert content.type == "text"
+    assert content.annotations is not None
+    assert len(content.annotations) == 1
+    annotation = content.annotations[0]
+    assert annotation["type"] == "citation"
+    assert annotation["file_id"] == "file-container123"
+    assert annotation["url"] == "data.csv"
+    assert annotation["additional_properties"]["container_id"] == "container-456"
+    assert annotation["annotated_regions"] is not None
+    assert len(annotation["annotated_regions"]) == 1
+    region = annotation["annotated_regions"][0]
+    assert region["start_index"] == 10
+    assert region["end_index"] == 50
 
 
 def test_streaming_annotation_added_with_url_citation() -> None:

python/packages/orchestrations/agent_framework_orchestrations/_base_group_chat_orchestrator.py

@@ -12,7 +12,7 @@ from collections.abc import Awaitable, Callable, Sequence
 from dataclasses import dataclass
 from typing import Any, ClassVar, TypeAlias
 
-from agent_framework._types import Message
+from agent_framework._types import AgentResponse, AgentResponseUpdate, Message
 from agent_framework._workflows._agent_executor import AgentExecutor, AgentExecutorRequest, AgentExecutorResponse
 from agent_framework._workflows._events import WorkflowEvent
 from agent_framework._workflows._executor import Executor, handler
@@ -351,8 +351,10 @@ class BaseGroupChatOrchestrator(Executor, ABC):
             result = await result
         return result
 
-    async def _check_terminate_and_yield(self, ctx: WorkflowContext[Never, list[Message]]) -> bool:
-        """Check termination conditions and yield completion if met.
+    async def _check_terminate_and_yield(
+        self, ctx: WorkflowContext[Never, AgentResponse | AgentResponseUpdate]
+    ) -> bool:
+        """Check termination conditions and yield the completion message if met.
 
         Args:
             ctx: Workflow context for yielding output
@@ -362,12 +364,37 @@ class BaseGroupChatOrchestrator(Executor, ABC):
         """
         terminate = await self._check_termination()
         if terminate:
-            self._append_messages([self._create_completion_message(self.TERMINATION_CONDITION_MET_MESSAGE)])
-            await ctx.yield_output(self._full_conversation)
+            completion_message = self._create_completion_message(self.TERMINATION_CONDITION_MET_MESSAGE)
+            self._append_messages([completion_message])
+            await self._yield_completion(ctx, completion_message)
             return True
 
         return False
 
+    async def _yield_completion(
+        self,
+        ctx: WorkflowContext[Never, AgentResponse | AgentResponseUpdate],
+        completion_message: Message,
+    ) -> None:
+        """Yield a synthesized terminal completion message in the right shape for the run mode.
+
+        Mode-aware to mirror ``AgentExecutor`` semantics:
+        - Streaming (``ctx.is_streaming()``): yield a single ``AgentResponseUpdate`` so the
+          ``output`` event stream stays uniformly per-chunk.
+        - Non-streaming: yield the full ``AgentResponse``.
+        """
+        if ctx.is_streaming():
+            await ctx.yield_output(
+                AgentResponseUpdate(
+                    contents=list(completion_message.contents),
+                    role=completion_message.role,
+                    author_name=completion_message.author_name,
+                    message_id=completion_message.message_id,
+                )
+            )
+        else:
+            await ctx.yield_output(AgentResponse(messages=[completion_message]))
+
     def _create_completion_message(self, message: str) -> Message:
         """Create a standardized completion message.
 
@@ -490,8 +517,10 @@ class BaseGroupChatOrchestrator(Executor, ABC):
 
         return False
 
-    async def _check_round_limit_and_yield(self, ctx: WorkflowContext[Never, list[Message]]) -> bool:
-        """Check round limit and yield completion if reached.
+    async def _check_round_limit_and_yield(
+        self, ctx: WorkflowContext[Never, AgentResponse | AgentResponseUpdate]
+    ) -> bool:
+        """Check round limit and yield the max-rounds completion message if reached.
 
         Args:
             ctx: Workflow context for yielding output
@@ -501,8 +530,9 @@ class BaseGroupChatOrchestrator(Executor, ABC):
         """
         reach_max_rounds = self._check_round_limit()
         if reach_max_rounds:
-            self._append_messages([self._create_completion_message(self.MAX_ROUNDS_MET_MESSAGE)])
-            await ctx.yield_output(self._full_conversation)
+            completion_message = self._create_completion_message(self.MAX_ROUNDS_MET_MESSAGE)
+            self._append_messages([completion_message])
+            await self._yield_completion(ctx, completion_message)
             return True
 
         return False

python/packages/orchestrations/agent_framework_orchestrations/_concurrent.py

@@ -6,7 +6,7 @@ import logging
 from collections.abc import Callable, Sequence
 from typing import Any
 
-from agent_framework import Message, SupportsAgentRun
+from agent_framework import AgentResponse, Message, SupportsAgentRun
 from agent_framework._workflows._agent_executor import AgentExecutor, AgentExecutorRequest, AgentExecutorResponse
 from agent_framework._workflows._agent_utils import resolve_agent_id
 from agent_framework._workflows._checkpoint import CheckpointStorage
@@ -71,18 +71,20 @@ class _DispatchToAllParticipants(Executor):
 
 
 class _AggregateAgentConversations(Executor):
-    """Aggregates agent responses and completes with combined ChatMessages.
+    """Aggregates agent responses and completes with a single AgentResponse.
 
-    Emits a list[Message] shaped as:
-      [ single_user_prompt?, agent1_final_assistant, agent2_final_assistant, ... ]
+    Emits an `AgentResponse` whose `messages` are the final assistant message from each
+    participant (one message per agent), in deterministic participant order matching
+    the fan-in `sources` configuration. The user prompt is intentionally not included —
+    that is part of the input, not the answer.
 
-    - Extracts a single user prompt (first user message seen across results).
-    - For each result, selects the final assistant message (prefers agent_response.messages).
-    - Avoids duplicating the same user message per agent.
+    For each participant the final assistant message is sourced from
+    `r.agent_response.messages`, falling back to scanning `r.full_conversation` for
+    pathological executors that did not populate the response.
     """
 
     @handler
-    async def aggregate(self, results: list[AgentExecutorResponse], ctx: WorkflowContext[Never, list[Message]]) -> None:
+    async def aggregate(self, results: list[AgentExecutorResponse], ctx: WorkflowContext[Never, AgentResponse]) -> None:
         if not results:
             logger.error("Concurrent aggregator received empty results list")
             raise ValueError("Aggregation failed: no results provided")
@@ -91,12 +93,10 @@ class _AggregateAgentConversations(Executor):
             r = getattr(msg, "role", None)
             if r is None:
                 return False
-            # Normalize both r and role to lowercase strings for comparison
             r_str = str(r).lower() if isinstance(r, str) or hasattr(r, "__str__") else r
             role_str = str(role).lower()
             return r_str == role_str
 
-        prompt_message: Message | None = None
         assistant_replies: list[Message] = []
 
         for r in results:
@@ -107,10 +107,6 @@ class _AggregateAgentConversations(Executor):
                 f"{len(resp_messages)} response msgs, {len(r.full_conversation)} conversation msgs"
             )
 
-            # Capture a single user prompt (first encountered across any conversation)
-            if prompt_message is None:
-                prompt_message = next((m for m in r.full_conversation if _is_role(m, "user")), None)
-
             # Pick the final assistant message from the response; fallback to conversation search
             final_assistant = next((m for m in reversed(resp_messages) if _is_role(m, "assistant")), None)
             if final_assistant is None:
@@ -127,14 +123,7 @@ class _AggregateAgentConversations(Executor):
             logger.error(f"Aggregation failed: no assistant replies found across {len(results)} results")
             raise RuntimeError("Aggregation failed: no assistant replies found")
 
-        output: list[Message] = []
-        if prompt_message is not None:
-            output.append(prompt_message)
-        else:
-            logger.warning("No user prompt found in any conversation; emitting assistants only")
-        output.extend(assistant_replies)
-
-        await ctx.yield_output(output)
+        await ctx.yield_output(AgentResponse(messages=assistant_replies))
 
 
 class _CallbackAggregator(Executor):
@@ -190,7 +179,8 @@ class ConcurrentBuilder:
 
         from agent_framework_orchestrations import ConcurrentBuilder
 
-        # Minimal: use default aggregator (returns list[Message])
+        # Minimal: use default aggregator (yields one AgentResponse with one assistant
+        # message per participant)
         workflow = ConcurrentBuilder(participants=[agent1, agent2, agent3]).build()
 
 
@@ -222,8 +212,9 @@ class ConcurrentBuilder:
         Args:
             participants: Sequence of agent or executor instances to run in parallel.
             checkpoint_storage: Optional checkpoint storage for enabling workflow state persistence.
-            intermediate_outputs: If True, enables intermediate outputs from agent participants
-                before aggregation.
+            intermediate_outputs: If True, every participant's `yield_output` surfaces as a
+                workflow `output` event in addition to the aggregator's. By default
+                (False) only the aggregator's output surfaces.
         """
         self._participants: list[SupportsAgentRun | Executor] = []
         self._aggregator: Executor | None = None
@@ -383,7 +374,7 @@ class ConcurrentBuilder:
         - If request info is enabled, the orchestration emits a request info event with outputs from all participants
             before sending the outputs to the aggregator
         - Aggregator yields output and the workflow becomes idle. The output is either:
-          - list[Message] (default aggregator: one user + one assistant per agent)
+          - AgentResponse (default aggregator: one assistant message per participant)
           - custom payload from the provided aggregator
 
         Returns:

python/packages/orchestrations/agent_framework_orchestrations/_group_chat.py

@@ -29,7 +29,7 @@ from collections.abc import Awaitable, Callable, Sequence
 from dataclasses import dataclass
 from typing import Any, ClassVar, cast
 
-from agent_framework import Agent, AgentSession, Message, SupportsAgentRun
+from agent_framework import Agent, AgentResponse, AgentResponseUpdate, AgentSession, Message, SupportsAgentRun
 from agent_framework._workflows._agent_executor import AgentExecutor, AgentExecutorRequest, AgentExecutorResponse
 from agent_framework._workflows._agent_utils import resolve_agent_id
 from agent_framework._workflows._checkpoint import CheckpointStorage
@@ -169,7 +169,9 @@ class GroupChatOrchestrator(BaseGroupChatOrchestrator):
         """Initialize orchestrator state and start the conversation loop."""
         self._append_messages(messages)
         # Termination condition will also be applied to the input messages
-        if await self._check_terminate_and_yield(cast(WorkflowContext[Never, list[Message]], ctx)):
+        if await self._check_terminate_and_yield(
+            cast(WorkflowContext[Never, AgentResponse | AgentResponseUpdate], ctx)
+        ):
             return
 
         next_speaker = await self._get_next_speaker()
@@ -198,9 +200,13 @@ class GroupChatOrchestrator(BaseGroupChatOrchestrator):
         messages = clean_conversation_for_handoff(messages)
         self._append_messages(messages)
 
-        if await self._check_terminate_and_yield(cast(WorkflowContext[Never, list[Message]], ctx)):
+        if await self._check_terminate_and_yield(
+            cast(WorkflowContext[Never, AgentResponse | AgentResponseUpdate], ctx)
+        ):
             return
-        if await self._check_round_limit_and_yield(cast(WorkflowContext[Never, list[Message]], ctx)):
+        if await self._check_round_limit_and_yield(
+            cast(WorkflowContext[Never, AgentResponse | AgentResponseUpdate], ctx)
+        ):
             return
 
         next_speaker = await self._get_next_speaker()
@@ -332,13 +338,15 @@ class AgentBasedGroupChatOrchestrator(BaseGroupChatOrchestrator):
         """Initialize orchestrator state and start the conversation loop."""
         self._append_messages(messages)
         # Termination condition will also be applied to the input messages
-        if await self._check_terminate_and_yield(cast(WorkflowContext[Never, list[Message]], ctx)):
+        if await self._check_terminate_and_yield(
+            cast(WorkflowContext[Never, AgentResponse | AgentResponseUpdate], ctx)
+        ):
             return
 
         agent_orchestration_output = await self._invoke_agent()
         if await self._check_agent_terminate_and_yield(
             agent_orchestration_output,
-            cast(WorkflowContext[Never, list[Message]], ctx),
+            cast(WorkflowContext[Never, AgentResponse | AgentResponseUpdate], ctx),
         ):
             return
 
@@ -366,15 +374,19 @@ class AgentBasedGroupChatOrchestrator(BaseGroupChatOrchestrator):
         # Remove tool-related content to prevent API errors from empty messages
         messages = clean_conversation_for_handoff(messages)
         self._append_messages(messages)
-        if await self._check_terminate_and_yield(cast(WorkflowContext[Never, list[Message]], ctx)):
+        if await self._check_terminate_and_yield(
+            cast(WorkflowContext[Never, AgentResponse | AgentResponseUpdate], ctx)
+        ):
             return
-        if await self._check_round_limit_and_yield(cast(WorkflowContext[Never, list[Message]], ctx)):
+        if await self._check_round_limit_and_yield(
+            cast(WorkflowContext[Never, AgentResponse | AgentResponseUpdate], ctx)
+        ):
             return
 
         agent_orchestration_output = await self._invoke_agent()
         if await self._check_agent_terminate_and_yield(
             agent_orchestration_output,
-            cast(WorkflowContext[Never, list[Message]], ctx),
+            cast(WorkflowContext[Never, AgentResponse | AgentResponseUpdate], ctx),
         ):
             return
 
@@ -522,9 +534,9 @@ class AgentBasedGroupChatOrchestrator(BaseGroupChatOrchestrator):
     async def _check_agent_terminate_and_yield(
         self,
         agent_orchestration_output: AgentOrchestrationOutput,
-        ctx: WorkflowContext[Never, list[Message]],
+        ctx: WorkflowContext[Never, AgentResponse | AgentResponseUpdate],
     ) -> bool:
-        """Check if the agent requested termination and yield completion if so.
+        """Yield the orchestrator's completion if termination was requested.
 
         Args:
             agent_orchestration_output: Output from the orchestrator agent
@@ -536,8 +548,9 @@ class AgentBasedGroupChatOrchestrator(BaseGroupChatOrchestrator):
             final_message = (
                 agent_orchestration_output.final_message or "The conversation has been terminated by the agent."
             )
-            self._append_messages([self._create_completion_message(final_message)])
-            await ctx.yield_output(self._full_conversation)
+            completion_message = self._create_completion_message(final_message)
+            self._append_messages([completion_message])
+            await self._yield_completion(ctx, completion_message)
             return True
 
         return False
@@ -622,7 +635,9 @@ class GroupChatBuilder:
                 True to terminate the conversation, False to continue.
             max_rounds: Optional maximum number of orchestrator rounds to prevent infinite conversations.
             checkpoint_storage: Optional checkpoint storage for enabling workflow state persistence.
-            intermediate_outputs: If True, enables intermediate outputs from agent participants.
+            intermediate_outputs: If True, every participant's `yield_output` surfaces as a
+                workflow `output` event in addition to the orchestrator's. By default (False)
+                only the orchestrator's output surfaces.
         """
         self._participants: dict[str, SupportsAgentRun | Executor] = {}
         self._participant_factories: list[Callable[[], SupportsAgentRun | Executor]] = []
@@ -643,8 +658,7 @@ class GroupChatBuilder:
         self._request_info_enabled: bool = False
         self._request_info_filter: set[str] = set()
 
-        # Intermediate outputs
-        self._intermediate_outputs = intermediate_outputs
+        self._intermediate_outputs: bool = intermediate_outputs
 
         if participants is None and participant_factories is None:
             raise ValueError("Either participants or participant_factories must be provided.")