chore: import upstream snapshot with attribution

dotnet/src/Microsoft.Agents.AI.DurableTask/AIAgentExtensions.cs

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Extension methods for the <see cref="AIAgent"/> class.
+/// </summary>
+public static class AIAgentExtensions
+{
+    /// <summary>
+    /// Converts an AIAgent to a durable agent proxy.
+    /// </summary>
+    /// <param name="agent">The agent to convert.</param>
+    /// <param name="services">The service provider.</param>
+    /// <returns>The durable agent proxy.</returns>
+    /// <exception cref="ArgumentException">
+    /// Thrown when the agent is a <see cref="DurableAIAgent"/> instance or if the agent has no name.
+    /// </exception>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown if <paramref name="services"/> does not contain an <see cref="IDurableAgentClient"/>
+    /// or if durable agents have not been configured on the service collection.
+    /// </exception>
+    /// <exception cref="AgentNotRegisteredException">
+    /// Thrown when the agent with the specified name has not been registered.
+    /// </exception>
+    public static AIAgent AsDurableAgentProxy(this AIAgent agent, IServiceProvider services)
+    {
+        // Don't allow this method to be used on DurableAIAgent instances.
+        if (agent is DurableAIAgent)
+        {
+            throw new ArgumentException(
+                $"{nameof(DurableAIAgent)} instances cannot be converted to a durable agent proxy.",
+                nameof(agent));
+        }
+
+        string agentName = agent.Name ?? throw new ArgumentException("Agent must have a name.", nameof(agent));
+
+        // Validate that the agent is registered
+        ServiceCollectionExtensions.ValidateAgentIsRegistered(services, agentName);
+
+        IDurableAgentClient agentClient = services.GetRequiredService<IDurableAgentClient>();
+        return new DurableAIAgentProxy(agentName, agentClient);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/AgentEntity.cs

@@ -0,0 +1,233 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.DurableTask.State;
+using Microsoft.DurableTask.Client;
+using Microsoft.DurableTask.Entities;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+internal class AgentEntity(IServiceProvider services, CancellationToken cancellationToken = default) : TaskEntity<DurableAgentState>
+{
+    private readonly IServiceProvider _services = services;
+    private readonly DurableTaskClient _client = services.GetRequiredService<DurableTaskClient>();
+    private readonly ILoggerFactory _loggerFactory = services.GetRequiredService<ILoggerFactory>();
+    private readonly IAgentResponseHandler? _messageHandler = services.GetService<IAgentResponseHandler>();
+    private readonly DurableAgentsOptions _options = services.GetRequiredService<DurableAgentsOptions>();
+    private readonly CancellationToken _cancellationToken = cancellationToken != default
+        ? cancellationToken
+        : services.GetService<IHostApplicationLifetime>()?.ApplicationStopping ?? CancellationToken.None;
+
+    public Task<AgentResponse> RunAgentAsync(RunRequest request)
+    {
+        return this.Run(request);
+    }
+
+    // IDE1006 and VSTHRD200 disabled to allow method name to match the common cross-platform entity operation name.
+#pragma warning disable IDE1006
+#pragma warning disable VSTHRD200
+    public async Task<AgentResponse> Run(RunRequest request)
+#pragma warning restore VSTHRD200
+#pragma warning restore IDE1006
+    {
+        AgentSessionId sessionId = this.Context.Id;
+        AIAgent agent = this.GetAgent(sessionId);
+        EntityAgentWrapper agentWrapper = new(agent, this.Context, request, this._services);
+
+        // Logger category is Microsoft.DurableTask.Agents.{agentName}.{sessionId}
+        ILogger logger = this.GetLogger(agent.Name!, sessionId.Key);
+
+        if (request.Messages.Count == 0)
+        {
+            logger.LogInformation("Ignoring empty request");
+            return new AgentResponse();
+        }
+
+        this.State.Data.ConversationHistory.Add(DurableAgentStateRequest.FromRunRequest(request));
+
+        foreach (ChatMessage msg in request.Messages)
+        {
+            logger.LogAgentRequest(sessionId, msg.Role, msg.Text);
+        }
+
+        // Set the current agent context for the duration of the agent run. This will be exposed
+        // to any tools that are invoked by the agent.
+        DurableAgentContext agentContext = new(
+            entityContext: this.Context,
+            client: this._client,
+            lifetime: this._services.GetRequiredService<IHostApplicationLifetime>(),
+            services: this._services);
+        DurableAgentContext.SetCurrent(agentContext);
+
+        try
+        {
+            // Start the agent response stream
+            IAsyncEnumerable<AgentResponseUpdate> responseStream = agentWrapper.RunStreamingAsync(
+                this.State.Data.ConversationHistory.SelectMany(e => e.Messages).Select(m => m.ToChatMessage()),
+                await agentWrapper.CreateSessionAsync(cancellationToken).ConfigureAwait(false),
+                options: null,
+                this._cancellationToken);
+
+            AgentResponse response;
+            if (this._messageHandler is null)
+            {
+                // If no message handler is provided, we can just get the full response at once.
+                // This is expected to be the common case for non-interactive agents.
+                response = await responseStream.ToAgentResponseAsync(this._cancellationToken);
+            }
+            else
+            {
+                List<AgentResponseUpdate> responseUpdates = [];
+
+                // To support interactive chat agents, we need to stream the responses to an IAgentMessageHandler.
+                // The user-provided message handler can be implemented to send the responses to the user.
+                // We assume that only non-empty text updates are useful for the user.
+                async IAsyncEnumerable<AgentResponseUpdate> StreamResultsAsync()
+                {
+                    await foreach (AgentResponseUpdate update in responseStream)
+                    {
+                        // We need the full response further down, so we piece it together as we go.
+                        responseUpdates.Add(update);
+
+                        // Yield the update to the message handler.
+                        yield return update;
+                    }
+                }
+
+                await this._messageHandler.OnStreamingResponseUpdateAsync(StreamResultsAsync(), this._cancellationToken);
+                response = responseUpdates.ToAgentResponse();
+            }
+
+            // Persist the agent response to the entity state for client polling
+            this.State.Data.ConversationHistory.Add(
+                DurableAgentStateResponse.FromResponse(request.CorrelationId, response));
+
+            string responseText = response.Text;
+
+            if (!string.IsNullOrEmpty(responseText))
+            {
+                logger.LogAgentResponse(
+                    sessionId,
+                    response.Messages.FirstOrDefault()?.Role ?? ChatRole.Assistant,
+                    responseText,
+                    response.Usage?.InputTokenCount,
+                    response.Usage?.OutputTokenCount,
+                    response.Usage?.TotalTokenCount);
+            }
+
+            // Update TTL expiration time. Only schedule deletion check on first interaction.
+            // Subsequent interactions just update the expiration time; CheckAndDeleteIfExpiredAsync
+            // will reschedule the deletion check when it runs.
+            TimeSpan? timeToLive = this._options.GetTimeToLive(sessionId.Name);
+            if (timeToLive.HasValue)
+            {
+                DateTime newExpirationTime = DateTime.UtcNow.Add(timeToLive.Value);
+                bool isFirstInteraction = this.State.Data.ExpirationTimeUtc is null;
+
+                this.State.Data.ExpirationTimeUtc = newExpirationTime;
+                logger.LogTTLExpirationTimeUpdated(sessionId, newExpirationTime);
+
+                // Only schedule deletion check on the first interaction when entity is created.
+                // On subsequent interactions, we just update the expiration time. The scheduled
+                // CheckAndDeleteIfExpiredAsync will reschedule itself if the entity hasn't expired.
+                if (isFirstInteraction)
+                {
+                    this.ScheduleDeletionCheck(sessionId, logger, timeToLive.Value);
+                }
+            }
+            else
+            {
+                // TTL is disabled. Clear the expiration time if it was previously set.
+                if (this.State.Data.ExpirationTimeUtc.HasValue)
+                {
+                    logger.LogTTLExpirationTimeCleared(sessionId);
+                    this.State.Data.ExpirationTimeUtc = null;
+                }
+            }
+
+            return response;
+        }
+        finally
+        {
+            // Clear the current agent context
+            DurableAgentContext.ClearCurrent();
+        }
+    }
+
+    /// <summary>
+    /// Checks if the entity has expired and deletes it if so, otherwise reschedules the deletion check.
+    /// </summary>
+    /// <remarks>
+    /// This method is called by the durable task runtime when a <c>CheckAndDeleteIfExpired</c> signal is received.
+    /// </remarks>
+    public void CheckAndDeleteIfExpired()
+    {
+        AgentSessionId sessionId = this.Context.Id;
+        AIAgent agent = this.GetAgent(sessionId);
+        ILogger logger = this.GetLogger(agent.Name!, sessionId.Key);
+
+        DateTime currentTime = DateTime.UtcNow;
+        DateTime? expirationTime = this.State.Data.ExpirationTimeUtc;
+
+        logger.LogTTLDeletionCheck(sessionId, expirationTime, currentTime);
+
+        if (expirationTime.HasValue)
+        {
+            if (currentTime >= expirationTime.Value)
+            {
+                // Entity has expired, delete it
+                logger.LogTTLEntityExpired(sessionId, expirationTime.Value);
+                this.State = null!;
+            }
+            else
+            {
+                // Entity hasn't expired yet, reschedule the deletion check
+                TimeSpan? timeToLive = this._options.GetTimeToLive(sessionId.Name);
+                if (timeToLive.HasValue)
+                {
+                    this.ScheduleDeletionCheck(sessionId, logger, timeToLive.Value);
+                }
+            }
+        }
+    }
+
+    private void ScheduleDeletionCheck(AgentSessionId sessionId, ILogger logger, TimeSpan timeToLive)
+    {
+        DateTime currentTime = DateTime.UtcNow;
+        DateTime expirationTime = this.State.Data.ExpirationTimeUtc ?? currentTime.Add(timeToLive);
+        TimeSpan minimumDelay = this._options.MinimumTimeToLiveSignalDelay;
+
+        // To avoid excessive scheduling, we schedule the deletion check for no less than the minimum delay.
+        DateTime scheduledTime = expirationTime > currentTime.Add(minimumDelay)
+            ? expirationTime
+            : currentTime.Add(minimumDelay);
+
+        logger.LogTTLDeletionScheduled(sessionId, scheduledTime);
+
+        // Schedule a signal to self to check for expiration
+        this.Context.SignalEntity(
+            this.Context.Id,
+            nameof(CheckAndDeleteIfExpired), // self-signal
+            options: new SignalEntityOptions { SignalTime = scheduledTime });
+    }
+
+    private AIAgent GetAgent(AgentSessionId sessionId)
+    {
+        IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>> agents =
+            this._services.GetRequiredService<IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>>>();
+        if (!agents.TryGetValue(sessionId.Name, out Func<IServiceProvider, AIAgent>? agentFactory))
+        {
+            throw new InvalidOperationException($"Agent '{sessionId.Name}' not found");
+        }
+
+        return agentFactory(this._services);
+    }
+
+    private ILogger GetLogger(string agentName, string sessionKey)
+    {
+        return this._loggerFactory.CreateLogger($"Microsoft.DurableTask.Agents.{agentName}.{sessionKey}");
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/AgentNotRegisteredException.cs

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Exception thrown when an agent with the specified name has not been registered.
+/// </summary>
+public sealed class AgentNotRegisteredException : InvalidOperationException
+{
+    // Not used, but required by static analysis.
+    private AgentNotRegisteredException()
+    {
+        this.AgentName = string.Empty;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentNotRegisteredException"/> class with the agent name.
+    /// </summary>
+    /// <param name="agentName">The name of the agent that was not registered.</param>
+    public AgentNotRegisteredException(string agentName)
+        : base(GetMessage(agentName))
+    {
+        this.AgentName = agentName;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentNotRegisteredException"/> class with the agent name and an inner exception.
+    /// </summary>
+    /// <param name="agentName">The name of the agent that was not registered.</param>
+    /// <param name="innerException">The exception that is the cause of the current exception.</param>
+    public AgentNotRegisteredException(string agentName, Exception? innerException)
+        : base(GetMessage(agentName), innerException)
+    {
+        this.AgentName = agentName;
+    }
+
+    /// <summary>
+    /// Gets the name of the agent that was not registered.
+    /// </summary>
+    public string AgentName { get; }
+
+    private static string GetMessage(string agentName)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(agentName);
+        return $"No agent named '{agentName}' was registered. Ensure the agent is registered using {nameof(ServiceCollectionExtensions.ConfigureDurableAgents)} before using it in an orchestration.";
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/AgentRunHandle.cs

@@ -0,0 +1,83 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.DurableTask.State;
+using Microsoft.DurableTask.Client;
+using Microsoft.DurableTask.Client.Entities;
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Represents a handle for a running agent request that can be used to retrieve the response.
+/// </summary>
+internal sealed class AgentRunHandle
+{
+    private readonly DurableTaskClient _client;
+    private readonly ILogger _logger;
+
+    internal AgentRunHandle(
+        DurableTaskClient client,
+        ILogger logger,
+        AgentSessionId sessionId,
+        string correlationId)
+    {
+        this._client = client;
+        this._logger = logger;
+        this.SessionId = sessionId;
+        this.CorrelationId = correlationId;
+    }
+
+    /// <summary>
+    /// Gets the correlation ID for this request.
+    /// </summary>
+    public string CorrelationId { get; }
+
+    /// <summary>
+    /// Gets the session ID for this request.
+    /// </summary>
+    public AgentSessionId SessionId { get; }
+
+    /// <summary>
+    /// Reads the agent response for this request by polling the entity state until the response is found.
+    /// Uses an exponential backoff polling strategy with a maximum interval of 1 second.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The agent response corresponding to this request.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the response is not found after polling.</exception>
+    public async Task<AgentResponse> ReadAgentResponseAsync(CancellationToken cancellationToken = default)
+    {
+        TimeSpan pollInterval = TimeSpan.FromMilliseconds(50); // Start with 50ms
+        TimeSpan maxPollInterval = TimeSpan.FromSeconds(3); // Maximum 3 seconds
+
+        this._logger.LogStartPollingForResponse(this.SessionId, this.CorrelationId);
+
+        while (true)
+        {
+            // Poll the entity state for responses
+            EntityMetadata<DurableAgentState>? entityResponse = await this._client.Entities.GetEntityAsync<DurableAgentState>(
+                this.SessionId,
+                cancellation: cancellationToken);
+            DurableAgentState? state = entityResponse?.State;
+
+            if (state?.Data.ConversationHistory is not null)
+            {
+                // Look for an agent response with matching CorrelationId
+                DurableAgentStateResponse? response = state.Data.ConversationHistory
+                    .OfType<DurableAgentStateResponse>()
+                    .FirstOrDefault(r => r.CorrelationId == this.CorrelationId);
+
+                if (response is not null)
+                {
+                    this._logger.LogDonePollingForResponse(this.SessionId, this.CorrelationId);
+                    return response.ToResponse();
+                }
+            }
+
+            // Wait before polling again with exponential backoff
+            await Task.Delay(pollInterval, cancellationToken);
+
+            // Double the poll interval, but cap it at the maximum
+            pollInterval = TimeSpan.FromMilliseconds(Math.Min(pollInterval.TotalMilliseconds * 2, maxPollInterval.TotalMilliseconds));
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/AgentSessionId.cs

@@ -0,0 +1,169 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.DurableTask.Entities;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Represents an agent session ID, which is used to identify a long-running agent session.
+/// </summary>
+[JsonConverter(typeof(AgentSessionIdJsonConverter))]
+public readonly struct AgentSessionId : IEquatable<AgentSessionId>
+{
+    private const string EntityNamePrefix = "dafx-";
+    private readonly EntityInstanceId _entityId;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentSessionId"/> struct.
+    /// </summary>
+    /// <param name="name">The name of the agent that owns the session (case-insensitive).</param>
+    /// <param name="key">The unique key of the agent session (case-sensitive).</param>
+    public AgentSessionId(string name, string key)
+    {
+        this.Name = name;
+        this._entityId = new EntityInstanceId(ToEntityName(name), key);
+    }
+
+    /// <summary>
+    /// Gets the name of the agent that owns the session. Names are case-insensitive.
+    /// </summary>
+    public string Name { get; }
+
+    /// <summary>
+    /// Gets the unique key of the agent session. Keys are case-sensitive and are used to identify the session.
+    /// </summary>
+    public string Key => this._entityId.Key;
+
+    /// <summary>
+    /// Converts an agent name to its underlying entity name representation.
+    /// </summary>
+    /// <param name="name">The agent name.</param>
+    /// <returns>The entity name used by Durable Task for this agent.</returns>
+    internal static string ToEntityName(string name) => $"{EntityNamePrefix}{name}";
+
+    /// <summary>
+    /// Converts the <see cref="AgentSessionId"/> to an <see cref="EntityInstanceId"/>.
+    /// </summary>
+    /// <returns>The <see cref="EntityInstanceId"/> representation of the <see cref="AgentSessionId"/>.</returns>
+    internal EntityInstanceId ToEntityId() => this._entityId;
+
+    /// <summary>
+    /// Creates a new <see cref="AgentSessionId"/> with the specified name and a randomly generated key.
+    /// </summary>
+    /// <param name="name">The name of the agent that owns the session.</param>
+    /// <returns>A new <see cref="AgentSessionId"/> with the specified name and a random key.</returns>
+    public static AgentSessionId WithRandomKey(string name) =>
+        new(name, Guid.NewGuid().ToString("N"));
+
+    /// <summary>
+    /// Determines whether two <see cref="AgentSessionId"/> instances are equal.
+    /// </summary>
+    /// <param name="left">The first <see cref="AgentSessionId"/> to compare.</param>
+    /// <param name="right">The second <see cref="AgentSessionId"/> to compare.</param>
+    /// <returns><c>true</c> if the two instances are equal; otherwise, <c>false</c>.</returns>
+    public static bool operator ==(AgentSessionId left, AgentSessionId right) =>
+        left._entityId == right._entityId;
+
+    /// <summary>
+    /// Determines whether two <see cref="AgentSessionId"/> instances are not equal.
+    /// </summary>
+    /// <param name="left">The first <see cref="AgentSessionId"/> to compare.</param>
+    /// <param name="right">The second <see cref="AgentSessionId"/> to compare.</param>
+    /// <returns><c>true</c> if the two instances are not equal; otherwise, <c>false</c>.</returns>
+    public static bool operator !=(AgentSessionId left, AgentSessionId right) =>
+        left._entityId != right._entityId;
+
+    /// <summary>
+    /// Determines whether the specified <see cref="AgentSessionId"/> is equal to the current <see cref="AgentSessionId"/>.
+    /// </summary>
+    /// <param name="other">The <see cref="AgentSessionId"/> to compare with the current <see cref="AgentSessionId"/>.</param>
+    /// <returns><c>true</c> if the specified <see cref="AgentSessionId"/> is equal to the current <see cref="AgentSessionId"/>; otherwise, <c>false</c>.</returns>
+    public bool Equals(AgentSessionId other) => this == other;
+
+    /// <summary>
+    /// Determines whether the specified object is equal to the current <see cref="AgentSessionId"/>.
+    /// </summary>
+    /// <param name="obj">The object to compare with the current <see cref="AgentSessionId"/>.</param>
+    /// <returns><c>true</c> if the specified object is equal to the current <see cref="AgentSessionId"/>; otherwise, <c>false</c>.</returns>
+    public override bool Equals(object? obj) => obj is AgentSessionId other && this == other;
+
+    /// <summary>
+    /// Returns the hash code for this <see cref="AgentSessionId"/>.
+    /// </summary>
+    /// <returns>A hash code for the current <see cref="AgentSessionId"/>.</returns>
+    public override int GetHashCode() => this._entityId.GetHashCode();
+
+    /// <summary>
+    /// Returns a string representation of this <see cref="AgentSessionId"/> in the form of @name@key.
+    /// </summary>
+    /// <returns>A string representation of the current <see cref="AgentSessionId"/>.</returns>
+    public override string ToString() => this._entityId.ToString();
+
+    /// <summary>
+    /// Converts the string representation of an agent session ID to its <see cref="AgentSessionId"/> equivalent.
+    /// The input string must be in the form of @name@key.
+    /// </summary>
+    /// <param name="sessionIdString">A string containing an agent session ID to convert.</param>
+    /// <returns>A <see cref="AgentSessionId"/> equivalent to the agent session ID contained in <paramref name="sessionIdString"/>.</returns>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="sessionIdString"/> is not a valid agent session ID format.</exception>
+    public static AgentSessionId Parse(string sessionIdString)
+    {
+        EntityInstanceId entityId = EntityInstanceId.FromString(sessionIdString);
+        if (!entityId.Name.StartsWith(EntityNamePrefix, StringComparison.OrdinalIgnoreCase))
+        {
+            throw new ArgumentException($"'{sessionIdString}' is not a valid agent session ID.", nameof(sessionIdString));
+        }
+
+        return new AgentSessionId(entityId.Name[EntityNamePrefix.Length..], entityId.Key);
+    }
+
+    /// <summary>
+    /// Implicitly converts an <see cref="AgentSessionId"/> to an <see cref="EntityInstanceId"/>.
+    /// This conversion is useful for entity API interoperability.
+    /// </summary>
+    /// <param name="agentSessionId">The <see cref="AgentSessionId"/> to convert.</param>
+    /// <returns>The equivalent <see cref="EntityInstanceId"/>.</returns>
+    public static implicit operator EntityInstanceId(AgentSessionId agentSessionId) => agentSessionId.ToEntityId();
+
+    /// <summary>
+    /// Implicitly converts an <see cref="EntityInstanceId"/> to an <see cref="AgentSessionId"/>.
+    /// </summary>
+    /// <param name="entityId">The <see cref="EntityInstanceId"/> to convert.</param>
+    /// <returns>The equivalent <see cref="AgentSessionId"/>.</returns>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1065:Do not raise exceptions in unexpected locations", Justification = "Implicit conversion must validate format.")]
+    public static implicit operator AgentSessionId(EntityInstanceId entityId)
+    {
+        if (!entityId.Name.StartsWith(EntityNamePrefix, StringComparison.OrdinalIgnoreCase))
+        {
+            throw new ArgumentException($"'{entityId}' is not a valid agent session ID.", nameof(entityId));
+        }
+        return new AgentSessionId(entityId.Name[EntityNamePrefix.Length..], entityId.Key);
+    }
+
+    /// <summary>
+    /// Custom JSON converter for <see cref="AgentSessionId"/> to ensure proper serialization and deserialization.
+    /// </summary>
+    public sealed class AgentSessionIdJsonConverter : JsonConverter<AgentSessionId>
+    {
+        /// <inheritdoc/>
+        public override AgentSessionId Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+        {
+            if (reader.TokenType != JsonTokenType.String)
+            {
+                throw new JsonException("Expected string value");
+            }
+
+            string value = reader.GetString() ?? string.Empty;
+
+            return Parse(value);
+        }
+
+        /// <inheritdoc/>
+        public override void Write(Utf8JsonWriter writer, AgentSessionId value, JsonSerializerOptions options)
+        {
+            writer.WriteStringValue(value.ToString());
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Release History
+
+## [Unreleased]
+
+- Fix issue with resuming checkpoint after package version upgrade ([#6670](https://github.com/microsoft/agent-framework/pull/6670))
+- Bind MCP threadId to the current agent and guard cross-agent session dispatch ([#6531](https://github.com/microsoft/agent-framework/pull/6531))
+- Added support for durable workflows ([#4436](https://github.com/microsoft/agent-framework/pull/4436))
+
+## v1.0.0-preview.260219.1
+
+- [BREAKING] Changed ChatHistory and AIContext Providers to have pipeline semantics ([#3806](https://github.com/microsoft/agent-framework/pull/3806))
+- Marked all `RunAsync<T>` overloads as `new`, added missing ones, and added support for primitives and arrays #3803
+- Improve session cast error message quality and consistency ([#3973](https://github.com/microsoft/agent-framework/pull/3973))
+
+## v1.0.0-preview.260212.1
+
+- [BREAKING] Changed AIAgent.SerializeSession to AIAgent.SerializeSessionAsync ([#3879](https://github.com/microsoft/agent-framework/pull/3879))
+
+## v1.0.0-preview.260209.1
+
+- [BREAKING] Introduce Core method pattern for Session management methods on AIAgent ([#3699](https://github.com/microsoft/agent-framework/pull/3699))
+
+## v1.0.0-preview.260205.1
+
+- [BREAKING] Moved AgentSession.Serialize to AIAgent.SerializeSession ([#3650](https://github.com/microsoft/agent-framework/pull/3650))
+- [BREAKING] Renamed serializedSession parameter to serializedState on DeserializeSessionAsync for consistency ([#3681](https://github.com/microsoft/agent-framework/pull/3681))
+
+## v1.0.0-preview.260127.1
+
+- [BREAKING] Renamed AgentThread to AgentSession ([#3430](https://github.com/microsoft/agent-framework/pull/3430))
+
+## v1.0.0-preview.260108.1
+
+- [BREAKING] Removed AgentThreadMetadata and used AgentSessionId directly instead ([#3067](https://github.com/microsoft/agent-framework/pull/3067))
+
+## v1.0.0-preview.251219.1
+
+- Filter empty `AIContent` from durable agent state responses ([#4670](https://github.com/microsoft/agent-framework/pull/4670))
+
+## v1.0.0-preview.260311.1
+
+### Changed
+
+- Added TTL configuration for durable agent entities ([#2679](https://github.com/microsoft/agent-framework/pull/2679))
+- Switch to new "Run" method name ([#2843](https://github.com/microsoft/agent-framework/pull/2843))
+
+NOTE: Some of the above changes may have been part of earlier releases not mentioned in this file.
+
+## v1.0.0-preview.251204.1
+
+- Added orchestration ID to durable agent entity state ([#2137](https://github.com/microsoft/agent-framework/pull/2137))
+
+## v1.0.0-preview.251125.1
+
+- Added support for .NET 10 ([#2128](https://github.com/microsoft/agent-framework/pull/2128))
+
+## v1.0.0-preview.251114.1
+
+- Added friendly error message when running durable agent that isn't registered ([#2214](https://github.com/microsoft/agent-framework/pull/2214))
+
+## v1.0.0-preview.251112.1
+
+- Initial public release ([#1916](https://github.com/microsoft/agent-framework/pull/1916))

dotnet/src/Microsoft.Agents.AI.DurableTask/DefaultDurableAgentClient.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.DurableTask.Client;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Logging.Abstractions;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+internal class DefaultDurableAgentClient(DurableTaskClient client, ILoggerFactory loggerFactory) : IDurableAgentClient
+{
+    private readonly DurableTaskClient _client = client ?? throw new ArgumentNullException(nameof(client));
+    private readonly ILogger _logger = (loggerFactory ?? NullLoggerFactory.Instance).CreateLogger<DefaultDurableAgentClient>();
+
+    public async Task<AgentRunHandle> RunAgentAsync(
+        AgentSessionId sessionId,
+        RunRequest request,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+
+        this._logger.LogSignallingAgent(sessionId);
+
+        await this._client.Entities.SignalEntityAsync(
+            sessionId,
+            nameof(AgentEntity.Run),
+            request,
+            cancellation: cancellationToken);
+
+        return new AgentRunHandle(this._client, this._logger, sessionId, request.CorrelationId);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAIAgent.cs

@@ -0,0 +1,296 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using Microsoft.DurableTask;
+using Microsoft.DurableTask.Entities;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// A durable AIAgent implementation that uses entity methods to interact with agent entities.
+/// </summary>
+public sealed class DurableAIAgent : AIAgent
+{
+    private readonly TaskOrchestrationContext _context;
+    private readonly string _agentName;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableAIAgent"/> class.
+    /// </summary>
+    /// <param name="context">The orchestration context.</param>
+    /// <param name="agentName">The name of the agent.</param>
+    internal DurableAIAgent(TaskOrchestrationContext context, string agentName)
+    {
+        this._context = context;
+        this._agentName = agentName;
+    }
+
+    /// <summary>
+    /// Creates a new agent session for this agent using a random session ID.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A value task that represents the asynchronous operation. The task result contains a new agent session.</returns>
+    protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
+    {
+        AgentSessionId sessionId = this._context.NewAgentSessionId(this._agentName);
+        return ValueTask.FromResult<AgentSession>(new DurableAgentSession(sessionId));
+    }
+
+    /// <summary>
+    /// Serializes an agent session to JSON.
+    /// </summary>
+    /// <param name="session">The session to serialize.</param>
+    /// <param name="jsonSerializerOptions">Optional JSON serializer options.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A <see cref="JsonElement"/> containing the serialized session state.</returns>
+    protected override ValueTask<JsonElement> SerializeSessionCoreAsync(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+    {
+        if (session is null)
+        {
+            throw new ArgumentNullException(nameof(session));
+        }
+
+        if (session is not DurableAgentSession durableSession)
+        {
+            throw new InvalidOperationException($"The provided session type '{session.GetType().Name}' is not compatible with this agent. Only sessions of type '{nameof(DurableAgentSession)}' can be serialized by this agent.");
+        }
+
+        return new(durableSession.Serialize(jsonSerializerOptions));
+    }
+
+    /// <summary>
+    /// Deserializes an agent session from JSON.
+    /// </summary>
+    /// <param name="serializedState">The serialized session data.</param>
+    /// <param name="jsonSerializerOptions">Optional JSON serializer options.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A value task that represents the asynchronous operation. The task result contains the deserialized agent session.</returns>
+    protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(
+        JsonElement serializedState,
+        JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+    {
+        return ValueTask.FromResult<AgentSession>(DurableAgentSession.Deserialize(serializedState, jsonSerializerOptions));
+    }
+
+    /// <summary>
+    /// Runs the agent with messages and returns the response.
+    /// </summary>
+    /// <param name="messages">The messages to send to the agent.</param>
+    /// <param name="session">The agent session to use.</param>
+    /// <param name="options">Optional run options.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The response from the agent.</returns>
+    /// <exception cref="AgentNotRegisteredException">Thrown when the agent has not been registered.</exception>
+    /// <exception cref="ArgumentException">Thrown when the provided session is not valid for a durable agent.</exception>
+    /// <exception cref="NotSupportedException">Thrown when cancellation is requested (cancellation is not supported for durable agents).</exception>
+    protected override async Task<AgentResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (cancellationToken != default && cancellationToken.CanBeCanceled)
+        {
+            throw new NotSupportedException("Cancellation is not supported for durable agents.");
+        }
+
+        session ??= await this.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
+        if (session is not DurableAgentSession durableSession)
+        {
+            throw new ArgumentException(
+                "The provided session is not valid for a durable agent. " +
+                "Create a new session using CreateSessionAsync or provide a session previously created by this agent.",
+                paramName: nameof(session));
+        }
+
+        IList<string>? enableToolNames = null;
+        bool enableToolCalls = true;
+        ChatResponseFormat? responseFormat = null;
+        if (options is DurableAgentRunOptions durableOptions)
+        {
+            enableToolCalls = durableOptions.EnableToolCalls;
+            enableToolNames = durableOptions.EnableToolNames;
+        }
+        else if (options is ChatClientAgentRunOptions chatClientOptions && chatClientOptions.ChatOptions?.Tools != null)
+        {
+            // Honor the response format from the chat client options if specified
+            responseFormat = chatClientOptions.ChatOptions?.ResponseFormat;
+        }
+
+        // Override the response format if specified in the agent run options
+        if (options?.ResponseFormat is { } format)
+        {
+            responseFormat = format;
+        }
+
+        RunRequest request = new([.. messages], responseFormat, enableToolCalls, enableToolNames)
+        {
+            OrchestrationId = this._context.InstanceId
+        };
+
+        try
+        {
+            return await this._context.Entities.CallEntityAsync<AgentResponse>(
+                durableSession.SessionId,
+                nameof(AgentEntity.Run),
+                request);
+        }
+        catch (EntityOperationFailedException e) when (e.FailureDetails.ErrorType == "EntityTaskNotFound")
+        {
+            throw new AgentNotRegisteredException(this._agentName, e);
+        }
+    }
+
+    /// <summary>
+    /// Runs the agent with messages and returns a simulated streaming response.
+    /// </summary>
+    /// <remarks>
+    /// Streaming is not supported for durable agents, so this method just returns the full response
+    /// as a single update.
+    /// </remarks>
+    /// <param name="messages">The messages to send to the agent.</param>
+    /// <param name="session">The agent session to use.</param>
+    /// <param name="options">Optional run options.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A streaming response enumerable.</returns>
+    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        // Streaming is not supported for durable agents, so we just return the full response
+        // as a single update.
+        AgentResponse response = await this.RunAsync(messages, session, options, cancellationToken);
+        foreach (AgentResponseUpdate update in response.ToAgentResponseUpdates())
+        {
+            yield return update;
+        }
+    }
+
+    /// <summary>
+    /// Run the agent with no message assuming that all required instructions are already provided to the agent or on the session, and requesting a response of the specified type <typeparamref name="T"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <remarks>
+    /// This method is specific to durable agents because the Durable Task Framework uses a custom
+    /// synchronization context for orchestration execution, and all continuations must run on the
+    /// orchestration thread to avoid breaking the durable orchestration and potential deadlocks.
+    /// </remarks>
+    public new Task<AgentResponse<T>> RunAsync<T>(
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default) =>
+        this.RunAsync<T>([], session, serializerOptions, options, cancellationToken);
+
+    /// <summary>
+    /// Runs the agent with a text message from the user, requesting a response of the specified type <typeparamref name="T"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="message">The user message to send to the agent.</param>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with the input message and any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <exception cref="ArgumentException"><paramref name="message"/> is <see langword="null"/>, empty, or contains only whitespace.</exception>
+    /// <remarks>
+    /// <inheritdoc cref="RunAsync{T}(AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken)" path="/remarks" />
+    /// </remarks>
+    public new Task<AgentResponse<T>> RunAsync<T>(
+        string message,
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(message);
+
+        return this.RunAsync<T>(new ChatMessage(ChatRole.User, message), session, serializerOptions, options, cancellationToken);
+    }
+
+    /// <summary>
+    /// Runs the agent with a single chat message, requesting a response of the specified type <typeparamref name="T"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="message">The chat message to send to the agent.</param>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with the input message and any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="message"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// <inheritdoc cref="RunAsync{T}(AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken)" path="/remarks" />
+    /// </remarks>
+    public new Task<AgentResponse<T>> RunAsync<T>(
+        ChatMessage message,
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        _ = Throw.IfNull(message);
+
+        return this.RunAsync<T>([message], session, serializerOptions, options, cancellationToken);
+    }
+
+    /// <summary>
+    /// Runs the agent with a collection of chat messages, requesting a response of the specified type <typeparamref name="T"/>.
+    /// </summary>
+    /// <typeparam name="T">The type of structured output to request.</typeparam>
+    /// <param name="messages">The collection of messages to send to the agent for processing.</param>
+    /// <param name="session">
+    /// The conversation session to use for this invocation. If <see langword="null"/>, a new session will be created.
+    /// The session will be updated with the input messages and any response messages generated during invocation.
+    /// </param>
+    /// <param name="serializerOptions">Optional JSON serializer options to use for deserializing the response.</param>
+    /// <param name="options">Optional configuration parameters for controlling the agent's invocation behavior.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A task that represents the asynchronous operation. The task result contains an <see cref="AgentResponse{T}"/> with the agent's output.</returns>
+    /// <remarks>
+    /// <inheritdoc cref="RunAsync{T}(AgentSession?, JsonSerializerOptions?, AgentRunOptions?, CancellationToken)" path="/remarks" />
+    /// </remarks>
+    public new async Task<AgentResponse<T>> RunAsync<T>(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        JsonSerializerOptions? serializerOptions = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        serializerOptions ??= AgentAbstractionsJsonUtilities.DefaultOptions;
+
+        var responseFormat = ChatResponseFormat.ForJsonSchema<T>(serializerOptions);
+
+        (responseFormat, bool isWrappedInObject) = StructuredOutputSchemaUtilities.WrapNonObjectSchema(responseFormat);
+
+        options = options?.Clone() ?? new DurableAgentRunOptions();
+        options.ResponseFormat = responseFormat;
+
+        // ConfigureAwait(false) cannot be used here because the Durable Task Framework uses
+        // a custom synchronization context that requires all continuations to execute on the
+        // orchestration thread. Scheduling the continuation on an arbitrary thread would break
+        // the orchestration.
+        AgentResponse response = await this.RunAsync(messages, session, options, cancellationToken);
+
+        return new AgentResponse<T>(response, serializerOptions) { IsWrappedInObject = isWrappedInObject };
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAIAgentProxy.cs

@@ -0,0 +1,110 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+internal class DurableAIAgentProxy(string name, IDurableAgentClient agentClient) : AIAgent
+{
+    private readonly IDurableAgentClient _agentClient = agentClient;
+
+    public override string? Name { get; } = name;
+
+    protected override ValueTask<JsonElement> SerializeSessionCoreAsync(AgentSession session, JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+    {
+        if (session is null)
+        {
+            throw new ArgumentNullException(nameof(session));
+        }
+
+        if (session is not DurableAgentSession durableSession)
+        {
+            throw new InvalidOperationException($"The provided session type '{session.GetType().Name}' is not compatible with this agent. Only sessions of type '{nameof(DurableAgentSession)}' can be serialized by this agent.");
+        }
+
+        return new(durableSession.Serialize(jsonSerializerOptions));
+    }
+
+    protected override ValueTask<AgentSession> DeserializeSessionCoreAsync(
+        JsonElement serializedState,
+        JsonSerializerOptions? jsonSerializerOptions = null, CancellationToken cancellationToken = default)
+    {
+        return ValueTask.FromResult<AgentSession>(DurableAgentSession.Deserialize(serializedState, jsonSerializerOptions));
+    }
+
+    protected override ValueTask<AgentSession> CreateSessionCoreAsync(CancellationToken cancellationToken = default)
+    {
+        return ValueTask.FromResult<AgentSession>(new DurableAgentSession(AgentSessionId.WithRandomKey(this.Name!)));
+    }
+
+    protected override async Task<AgentResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        session ??= await this.CreateSessionAsync(cancellationToken).ConfigureAwait(false);
+        if (session is not DurableAgentSession durableSession)
+        {
+            throw new ArgumentException(
+                "The provided session is not valid for a durable agent. " +
+                "Create a new session using CreateSessionAsync or provide a session previously created by this agent.",
+                paramName: nameof(session));
+        }
+
+        IList<string>? enableToolNames = null;
+        bool enableToolCalls = true;
+        ChatResponseFormat? responseFormat = null;
+        bool isFireAndForget = false;
+
+        if (options is DurableAgentRunOptions durableOptions)
+        {
+            enableToolCalls = durableOptions.EnableToolCalls;
+            enableToolNames = durableOptions.EnableToolNames;
+            isFireAndForget = durableOptions.IsFireAndForget;
+        }
+        else if (options is ChatClientAgentRunOptions chatClientOptions)
+        {
+            // Honor the response format from the chat client options if specified
+            responseFormat = chatClientOptions.ChatOptions?.ResponseFormat;
+        }
+
+        // Override the response format if specified in the agent run options
+        if (options?.ResponseFormat is { } format)
+        {
+            responseFormat = format;
+        }
+
+        RunRequest request = new([.. messages], responseFormat, enableToolCalls, enableToolNames);
+        AgentSessionId sessionId = durableSession.SessionId;
+
+        // The session must belong to this agent.
+        if (!string.Equals(sessionId.Name, this.Name, StringComparison.OrdinalIgnoreCase))
+        {
+            throw new ArgumentException(
+                $"The provided session belongs to agent '{sessionId.Name}' but was passed to agent '{this.Name}'. " +
+                "Sessions cannot be reused across agents.",
+                paramName: nameof(session));
+        }
+
+        AgentRunHandle agentRunHandle = await this._agentClient.RunAgentAsync(sessionId, request, cancellationToken);
+
+        if (isFireAndForget)
+        {
+            // If the request is fire and forget, return an empty response.
+            return new AgentResponse();
+        }
+
+        return await agentRunHandle.ReadAgentResponseAsync(cancellationToken);
+    }
+
+    protected override IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        throw new NotSupportedException("Streaming is not supported for durable agents.");
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAgentContext.cs

@@ -0,0 +1,161 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.DurableTask;
+using Microsoft.DurableTask.Client;
+using Microsoft.DurableTask.Entities;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// A context for durable agents that provides access to orchestration capabilities.
+/// This class provides thread-static access to the current agent context.
+/// </summary>
+public class DurableAgentContext
+{
+    private static readonly AsyncLocal<DurableAgentContext?> s_currentContext = new();
+    private readonly IServiceProvider _services;
+    private readonly CancellationToken _cancellationToken;
+
+    internal DurableAgentContext(
+        TaskEntityContext entityContext,
+        DurableTaskClient client,
+        IHostApplicationLifetime lifetime,
+        IServiceProvider services)
+    {
+        this.EntityContext = entityContext;
+        this.CurrentSession = new DurableAgentSession(entityContext.Id);
+        this.Client = client;
+        this._services = services;
+        this._cancellationToken = lifetime.ApplicationStopping;
+    }
+
+    /// <summary>
+    /// Gets the current durable agent context instance.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Thrown when no agent context is available.</exception>
+    public static DurableAgentContext Current => s_currentContext.Value ??
+        throw new InvalidOperationException("No agent context found!");
+
+    /// <summary>
+    /// Gets the entity context for this agent.
+    /// </summary>
+    public TaskEntityContext EntityContext { get; }
+
+    /// <summary>
+    /// Gets the durable task client for this agent.
+    /// </summary>
+    public DurableTaskClient Client { get; }
+
+    /// <summary>
+    /// Gets the current agent thread.
+    /// </summary>
+    public DurableAgentSession CurrentSession { get; }
+
+    /// <summary>
+    /// Sets the current durable agent context instance.
+    /// This is called internally by the agent entity during execution.
+    /// </summary>
+    /// <param name="context">The context instance to set.</param>
+    internal static void SetCurrent(DurableAgentContext context)
+    {
+        if (s_currentContext.Value is not null)
+        {
+            throw new InvalidOperationException("A DurableAgentContext has already been set for this AsyncLocal context.");
+        }
+
+        s_currentContext.Value = context;
+    }
+
+    /// <summary>
+    /// Clears the current durable agent context instance.
+    /// This is called internally by the agent entity after execution.
+    /// </summary>
+    internal static void ClearCurrent()
+    {
+        s_currentContext.Value = null;
+    }
+
+    /// <summary>
+    /// Schedules a new orchestration instance.
+    /// </summary>
+    /// <remarks>
+    /// When run in the context of a durable agent tool, the actual scheduling of the orchestration
+    /// occurs after the completion of the tool call. This allows the durable scheduling of the orchestration
+    /// and the agent state update to be committed atomically in a single transaction.
+    /// </remarks>
+    /// <param name="name">The name of the orchestration to schedule.</param>
+    /// <param name="input">The input to the orchestration.</param>
+    /// <param name="options">The options for the orchestration.</param>
+    /// <returns>The instance ID of the scheduled orchestration.</returns>
+    public string ScheduleNewOrchestration(
+        TaskName name,
+        object? input = null,
+        StartOrchestrationOptions? options = null)
+    {
+        return this.EntityContext.ScheduleNewOrchestration(name, input, options);
+    }
+
+    /// <summary>
+    /// Gets the status of an orchestration instance.
+    /// </summary>
+    /// <param name="instanceId">The instance ID of the orchestration to get the status of.</param>
+    /// <param name="includeDetails">Whether to include detailed information about the orchestration.</param>
+    /// <returns>The status of the orchestration.</returns>
+    public Task<OrchestrationMetadata?> GetOrchestrationStatusAsync(string instanceId, bool includeDetails = false)
+    {
+        return this.Client.GetInstanceAsync(instanceId, includeDetails, this._cancellationToken);
+    }
+
+    /// <summary>
+    /// Raises an event on an orchestration instance.
+    /// </summary>
+    /// <param name="instanceId">The instance ID of the orchestration to raise the event on.</param>
+    /// <param name="eventName">The name of the event to raise.</param>
+    /// <param name="eventData">The data to send with the event.</param>
+#pragma warning disable CA1030 // Use events where appropriate
+    public Task RaiseOrchestrationEventAsync(string instanceId, string eventName, object? eventData = null)
+#pragma warning restore CA1030 // Use events where appropriate
+    {
+        return this.Client.RaiseEventAsync(instanceId, eventName, eventData, this._cancellationToken);
+    }
+
+    /// <summary>
+    /// Asks the <see cref="DurableAgentContext"/> for an object of the specified type, <typeparamref name="TService"/>.
+    /// </summary>
+    /// <typeparam name="TService">The type of the object being requested.</typeparam>
+    /// <param name="serviceKey">An optional key to identify the service instance.</param>
+    /// <returns>The service instance, or <see langword="null"/> if the service is not found.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when <paramref name="serviceKey"/> is not <see langword="null"/> and the service provider does not support keyed services.
+    /// </exception>
+    public TService? GetService<TService>(object? serviceKey = null)
+    {
+        return this.GetService(typeof(TService), serviceKey) is TService service ? service : default;
+    }
+
+    /// <summary>
+    /// Asks the <see cref="DurableAgentContext"/> for an object of the specified type, <paramref name="serviceType"/>.
+    /// </summary>
+    /// <param name="serviceType">The type of the object being requested.</param>
+    /// <param name="serviceKey">An optional key to identify the service instance.</param>
+    /// <returns>The service instance, or <see langword="null"/> if the service is not found.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when <paramref name="serviceKey"/> is not <see langword="null"/> and the service provider does not support keyed services.
+    /// </exception>
+    public object? GetService(Type serviceType, object? serviceKey = null)
+    {
+        if (serviceKey is not null)
+        {
+            if (this._services is not IKeyedServiceProvider keyedServiceProvider)
+            {
+                throw new InvalidOperationException("The service provider does not support keyed services.");
+            }
+
+            return keyedServiceProvider.GetKeyedService(serviceType, serviceKey);
+        }
+
+        return this._services.GetService(serviceType);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAgentJsonUtilities.cs

@@ -0,0 +1,99 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Encodings.Web;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Agents.AI.DurableTask.State;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>Provides JSON serialization utilities and source-generated contracts for Durable Agent types.</summary>
+/// <remarks>
+/// <para>
+/// This mirrors the pattern used by other libraries (e.g. <c>WorkflowsJsonUtilities</c>) to enable Native AOT and trimming
+/// friendly serialization without relying on runtime reflection. It establishes a singleton <see cref="JsonSerializerOptions"/>
+/// instance that is preconfigured with:
+/// </para>
+/// <list type="number">
+/// <item><description><see cref="JsonSerializerDefaults.Web"/> baseline defaults.</description></item>
+/// <item><description><see cref="JsonIgnoreCondition.WhenWritingNull"/> for default null-value suppression.</description></item>
+/// <item><description><see cref="JsonNumberHandling.AllowReadingFromString"/> to tolerate numbers encoded as strings.</description></item>
+/// <item><description>Chained type info resolvers from shared agent abstractions to cover cross-package types (e.g. <see cref="ChatMessage"/>, <see cref="AgentResponse"/>).</description></item>
+/// </list>
+/// <para>
+/// Keep the list of <c>[JsonSerializable]</c> types in sync with the Durable Agent data model anytime new state or request/response
+/// containers are introduced that must round-trip via JSON.
+/// </para>
+/// </remarks>
+internal static partial class DurableAgentJsonUtilities
+{
+    /// <summary>
+    /// Gets the singleton <see cref="JsonSerializerOptions"/> used for Durable Agent serialization.
+    /// </summary>
+    public static JsonSerializerOptions DefaultOptions { get; } = CreateDefaultOptions();
+
+    /// <summary>
+    /// Serializes a sequence of chat messages using the durable agent default options.
+    /// </summary>
+    /// <param name="messages">The messages to serialize.</param>
+    /// <returns>A <see cref="JsonElement"/> representing the serialized messages.</returns>
+    public static JsonElement Serialize(this IEnumerable<ChatMessage> messages) =>
+        JsonSerializer.SerializeToElement(messages, DefaultOptions.GetTypeInfo(typeof(IEnumerable<ChatMessage>)));
+
+    /// <summary>
+    /// Deserializes chat messages from a <see cref="JsonElement"/> using durable agent options.
+    /// </summary>
+    /// <param name="element">The JSON element containing the messages.</param>
+    /// <returns>The deserialized list of chat messages.</returns>
+    public static List<ChatMessage> DeserializeMessages(this JsonElement element) =>
+        (List<ChatMessage>?)element.Deserialize(DefaultOptions.GetTypeInfo(typeof(List<ChatMessage>))) ?? [];
+
+    /// <summary>
+    /// Creates the configured <see cref="JsonSerializerOptions"/> instance for durable agents.
+    /// </summary>
+    /// <returns>The configured options.</returns>
+    [UnconditionalSuppressMessage("ReflectionAnalysis", "IL3050:RequiresDynamicCode", Justification = "Converter is guarded by IsReflectionEnabledByDefault check.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026:Members annotated with 'RequiresUnreferencedCodeAttribute' require dynamic access", Justification = "Converter is guarded by IsReflectionEnabledByDefault check.")]
+    private static JsonSerializerOptions CreateDefaultOptions()
+    {
+        // Base configuration from the source-generated context below.
+        JsonSerializerOptions options = new(JsonContext.Default.Options)
+        {
+            Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping, // same as AgentAbstractionsJsonUtilities and AIJsonUtilities
+        };
+
+        // Chain in shared abstractions resolver (Microsoft.Extensions.AI + Agent abstractions) so dependent types are covered.
+        options.TypeInfoResolverChain.Clear();
+        options.TypeInfoResolverChain.Add(AgentAbstractionsJsonUtilities.DefaultOptions.TypeInfoResolver!);
+        options.TypeInfoResolverChain.Add(JsonContext.Default.Options.TypeInfoResolver!);
+
+        if (JsonSerializer.IsReflectionEnabledByDefault)
+        {
+            options.Converters.Add(new JsonStringEnumConverter());
+        }
+
+        options.MakeReadOnly();
+        return options;
+    }
+
+    // Keep in sync with CreateDefaultOptions above.
+    [JsonSourceGenerationOptions(JsonSerializerDefaults.Web,
+        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+        NumberHandling = JsonNumberHandling.AllowReadingFromString)]
+
+    // Durable Agent State Types
+    [JsonSerializable(typeof(DurableAgentState))]
+    [JsonSerializable(typeof(DurableAgentSession))]
+
+    // Request Types
+    [JsonSerializable(typeof(RunRequest))]
+
+    // Primitive / Supporting Types
+    [JsonSerializable(typeof(ChatMessage))]
+    [JsonSerializable(typeof(JsonElement))]
+
+    [ExcludeFromCodeCoverage]
+    internal sealed partial class JsonContext : JsonSerializerContext;
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAgentRunOptions.cs

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Options for running a durable agent.
+/// </summary>
+public sealed class DurableAgentRunOptions : AgentRunOptions
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableAgentRunOptions"/> class.
+    /// </summary>
+    public DurableAgentRunOptions()
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableAgentRunOptions"/> class by copying values from the specified options.
+    /// </summary>
+    /// <param name="options">The options instance from which to copy values.</param>
+    private DurableAgentRunOptions(DurableAgentRunOptions options)
+        : base(options)
+    {
+        this.EnableToolCalls = options.EnableToolCalls;
+        this.EnableToolNames = options.EnableToolNames is not null ? new List<string>(options.EnableToolNames) : null;
+        this.IsFireAndForget = options.IsFireAndForget;
+    }
+
+    /// <summary>
+    /// Gets or sets whether to enable tool calls for this request.
+    /// </summary>
+    public bool EnableToolCalls { get; set; } = true;
+
+    /// <summary>
+    /// Gets or sets the collection of tool names to enable. If not specified, all tools are enabled.
+    /// </summary>
+    public IList<string>? EnableToolNames { get; set; }
+
+    /// <summary>
+    /// Gets or sets whether to fire and forget the agent run request.
+    /// </summary>
+    /// <remarks>
+    /// If <see cref="IsFireAndForget"/> is <c>true</c>, the agent run request will be sent and the method will return immediately.
+    /// The caller will not wait for the agent to complete the run and will not receive a response. This setting is useful for
+    /// long-running tasks where the caller does not need to wait for the agent to complete the run.
+    /// </remarks>
+    public bool IsFireAndForget { get; set; }
+
+    /// <inheritdoc/>
+    public override AgentRunOptions Clone() => new DurableAgentRunOptions(this);
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAgentSession.cs

@@ -0,0 +1,83 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// An <see cref="AgentSession"/> implementation for durable agents.
+/// </summary>
+[DebuggerDisplay("{DebuggerDisplay,nq}")]
+public sealed class DurableAgentSession : AgentSession
+{
+    internal DurableAgentSession(AgentSessionId sessionId)
+    {
+        this.SessionId = sessionId;
+    }
+
+    [JsonConstructor]
+    internal DurableAgentSession(AgentSessionId sessionId, AgentSessionStateBag stateBag) : base(stateBag)
+    {
+        this.SessionId = sessionId;
+    }
+
+    /// <summary>
+    /// Gets the agent session ID.
+    /// </summary>
+    [JsonInclude]
+    [JsonPropertyName("sessionId")]
+    internal AgentSessionId SessionId { get; }
+
+    /// <inheritdoc/>
+    internal JsonElement Serialize(JsonSerializerOptions? jsonSerializerOptions = null)
+    {
+        var jso = jsonSerializerOptions ?? DurableAgentJsonUtilities.DefaultOptions;
+        return JsonSerializer.SerializeToElement(this, jso.GetTypeInfo(typeof(DurableAgentSession)));
+    }
+
+    /// <summary>
+    /// Deserializes a DurableAgentSession from JSON.
+    /// </summary>
+    /// <param name="serializedSession">The serialized thread data.</param>
+    /// <param name="jsonSerializerOptions">Optional JSON serializer options.</param>
+    /// <returns>The deserialized DurableAgentSession.</returns>
+    internal static DurableAgentSession Deserialize(JsonElement serializedSession, JsonSerializerOptions? jsonSerializerOptions = null)
+    {
+        if (!serializedSession.TryGetProperty("sessionId", out JsonElement sessionIdElement) ||
+            sessionIdElement.ValueKind != JsonValueKind.String)
+        {
+            throw new JsonException("Invalid or missing sessionId property.");
+        }
+
+        string sessionIdString = sessionIdElement.GetString() ?? throw new JsonException("sessionId property is null.");
+        AgentSessionId sessionId = AgentSessionId.Parse(sessionIdString);
+        AgentSessionStateBag stateBag = serializedSession.TryGetProperty("stateBag", out JsonElement stateBagElement)
+            ? AgentSessionStateBag.Deserialize(stateBagElement)
+            : new AgentSessionStateBag();
+
+        return new DurableAgentSession(sessionId, stateBag);
+    }
+
+    /// <inheritdoc/>
+    public override object? GetService(Type serviceType, object? serviceKey = null)
+    {
+        if (serviceType == typeof(AgentSessionId))
+        {
+            return this.SessionId;
+        }
+
+        return base.GetService(serviceType, serviceKey);
+    }
+
+    /// <inheritdoc/>
+    public override string ToString()
+    {
+        return this.SessionId.ToString();
+    }
+
+    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
+    private string DebuggerDisplay =>
+        $"SessionId = {this.SessionId}, StateBag Count = {this.StateBag.Count}";
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableAgentsOptions.cs

@@ -0,0 +1,155 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Builder for configuring durable agents.
+/// </summary>
+public sealed class DurableAgentsOptions
+{
+    // Agent names are case-insensitive
+    private readonly Dictionary<string, Func<IServiceProvider, AIAgent>> _agentFactories = new(StringComparer.OrdinalIgnoreCase);
+    private readonly Dictionary<string, TimeSpan?> _agentTimeToLive = new(StringComparer.OrdinalIgnoreCase);
+
+    internal DurableAgentsOptions()
+    {
+    }
+
+    /// <summary>
+    /// Gets or sets the default time-to-live (TTL) for agent entities.
+    /// </summary>
+    /// <remarks>
+    /// If an agent entity is idle for this duration, it will be automatically deleted.
+    /// Defaults to 14 days. Set to <see langword="null"/> to disable TTL for agents without explicit TTL configuration.
+    /// </remarks>
+    public TimeSpan? DefaultTimeToLive { get; set; } = TimeSpan.FromDays(14);
+
+    /// <summary>
+    /// Gets or sets the minimum delay for scheduling TTL deletion signals. Defaults to 5 minutes.
+    /// </summary>
+    /// <remarks>
+    /// This property is primarily useful for testing (where shorter delays are needed) or for
+    /// shorter-lived agents in workflows that need more rapid cleanup. The maximum allowed value is 5 minutes.
+    /// Reducing the minimum deletion delay below 5 minutes can be useful for testing or for ensuring rapid cleanup of short-lived agent sessions.
+    /// However, this can also increase the load on the system and should be used with caution.
+    /// </remarks>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown when the value exceeds 5 minutes.</exception>
+    public TimeSpan MinimumTimeToLiveSignalDelay
+    {
+        get;
+        set
+        {
+            const int MaximumDelayMinutes = 5;
+            if (value > TimeSpan.FromMinutes(MaximumDelayMinutes))
+            {
+                throw new ArgumentOutOfRangeException(
+                    nameof(value),
+                    value,
+                    $"The minimum time-to-live signal delay cannot exceed {MaximumDelayMinutes} minutes.");
+            }
+
+            field = value;
+        }
+    } = TimeSpan.FromMinutes(5);
+
+    /// <summary>
+    /// Adds an AI agent factory to the options.
+    /// </summary>
+    /// <param name="name">The name of the agent.</param>
+    /// <param name="factory">The factory function to create the agent.</param>
+    /// <param name="timeToLive">Optional time-to-live for this agent's entities. If not specified, uses <see cref="DefaultTimeToLive"/>.</param>
+    /// <returns>The options instance.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="name"/> or <paramref name="factory"/> is null.</exception>
+    public DurableAgentsOptions AddAIAgentFactory(string name, Func<IServiceProvider, AIAgent> factory, TimeSpan? timeToLive = null)
+    {
+        ArgumentNullException.ThrowIfNull(name);
+        ArgumentNullException.ThrowIfNull(factory);
+        this._agentFactories.Add(name, factory);
+        if (timeToLive.HasValue)
+        {
+            this._agentTimeToLive[name] = timeToLive;
+        }
+
+        return this;
+    }
+
+    /// <summary>
+    /// Adds a list of AI agents to the options.
+    /// </summary>
+    /// <param name="agents">The list of agents to add.</param>
+    /// <returns>The options instance.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="agents"/> is null.</exception>
+    public DurableAgentsOptions AddAIAgents(params IEnumerable<AIAgent> agents)
+    {
+        ArgumentNullException.ThrowIfNull(agents);
+        foreach (AIAgent agent in agents)
+        {
+            this.AddAIAgent(agent);
+        }
+
+        return this;
+    }
+
+    /// <summary>
+    /// Adds an AI agent to the options.
+    /// </summary>
+    /// <param name="agent">The agent to add.</param>
+    /// <param name="timeToLive">Optional time-to-live for this agent's entities. If not specified, uses <see cref="DefaultTimeToLive"/>.</param>
+    /// <returns>The options instance.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="agent"/> is null.</exception>
+    /// <exception cref="ArgumentException">
+    /// Thrown when <paramref name="agent.Name"/> is null or whitespace or when an agent with the same name has already been registered.
+    /// </exception>
+    public DurableAgentsOptions AddAIAgent(AIAgent agent, TimeSpan? timeToLive = null)
+    {
+        ArgumentNullException.ThrowIfNull(agent);
+
+        if (string.IsNullOrWhiteSpace(agent.Name))
+        {
+            throw new ArgumentException($"{nameof(agent.Name)} must not be null or whitespace.", nameof(agent));
+        }
+
+        if (this._agentFactories.ContainsKey(agent.Name))
+        {
+            throw new ArgumentException($"An agent with name '{agent.Name}' has already been registered.", nameof(agent));
+        }
+
+        this._agentFactories.Add(agent.Name, sp => agent);
+        if (timeToLive.HasValue)
+        {
+            this._agentTimeToLive[agent.Name] = timeToLive;
+        }
+
+        return this;
+    }
+
+    /// <summary>
+    /// Gets the agents that have been added to this builder.
+    /// </summary>
+    /// <returns>A read-only collection of agents.</returns>
+    internal IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>> GetAgentFactories()
+    {
+        return this._agentFactories.AsReadOnly();
+    }
+
+    /// <summary>
+    /// Gets the time-to-live for a specific agent, or the default TTL if not specified.
+    /// </summary>
+    /// <param name="agentName">The name of the agent.</param>
+    /// <returns>The time-to-live for the agent, or the default TTL if not specified.</returns>
+    internal TimeSpan? GetTimeToLive(string agentName)
+    {
+        return this._agentTimeToLive.TryGetValue(agentName, out TimeSpan? ttl) ? ttl : this.DefaultTimeToLive;
+    }
+
+    /// <summary>
+    /// Determines whether an agent with the specified name is registered.
+    /// </summary>
+    /// <param name="agentName">The name of the agent to locate. Cannot be null.</param>
+    /// <returns>true if an agent with the specified name is registered; otherwise, false.</returns>
+    internal bool ContainsAgent(string agentName)
+    {
+        ArgumentNullException.ThrowIfNull(agentName);
+        return this._agentFactories.ContainsKey(agentName);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableDataConverter.cs

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
+using System.Text.Json.Serialization.Metadata;
+using Microsoft.Agents.AI.DurableTask.State;
+using Microsoft.DurableTask;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Custom data converter for durable agents and workflows that ensures proper JSON serialization.
+/// </summary>
+/// <remarks>
+/// This converter handles special cases like <see cref="DurableAgentState"/> using source-generated
+/// JSON contexts for AOT compatibility, and falls back to reflection-based serialization for other types.
+/// </remarks>
+internal sealed class DurableDataConverter : DataConverter
+{
+    private static readonly JsonSerializerOptions s_options = new(DurableAgentJsonUtilities.DefaultOptions)
+    {
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        PropertyNameCaseInsensitive = true,
+    };
+
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Fallback uses reflection when metadata unavailable.")]
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Fallback uses reflection when metadata unavailable.")]
+    public override object? Deserialize(string? data, Type targetType)
+    {
+        if (data is null)
+        {
+            return null;
+        }
+
+        if (targetType == typeof(DurableAgentState))
+        {
+            return JsonSerializer.Deserialize(data, DurableAgentStateJsonContext.Default.DurableAgentState);
+        }
+
+        JsonTypeInfo? typeInfo = s_options.GetTypeInfo(targetType);
+        return typeInfo is not null
+            ? JsonSerializer.Deserialize(data, typeInfo)
+            : JsonSerializer.Deserialize(data, targetType, s_options);
+    }
+
+    [return: NotNullIfNotNull(nameof(value))]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Fallback uses reflection when metadata unavailable.")]
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Fallback uses reflection when metadata unavailable.")]
+    public override string? Serialize(object? value)
+    {
+        if (value is null)
+        {
+            return null;
+        }
+
+        if (value is DurableAgentState durableAgentState)
+        {
+            return JsonSerializer.Serialize(durableAgentState, DurableAgentStateJsonContext.Default.DurableAgentState);
+        }
+
+        JsonTypeInfo? typeInfo = s_options.GetTypeInfo(value.GetType());
+        return typeInfo is not null
+            ? JsonSerializer.Serialize(value, typeInfo)
+            : JsonSerializer.Serialize(value, s_options);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableOptions.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using Microsoft.Agents.AI.DurableTask.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Provides configuration options for durable agents and workflows.
+/// </summary>
+[DebuggerDisplay("Workflows = {Workflows.Workflows.Count}, Agents = {Agents.AgentCount}")]
+public class DurableOptions
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableOptions"/> class.
+    /// </summary>
+    internal DurableOptions()
+    {
+        this.Workflows = new DurableWorkflowOptions(this);
+    }
+
+    /// <summary>
+    /// Gets the configuration options for durable agents.
+    /// </summary>
+    public DurableAgentsOptions Agents { get; } = new();
+
+    /// <summary>
+    /// Gets the configuration options for durable workflows.
+    /// </summary>
+    public DurableWorkflowOptions Workflows { get; }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/DurableServicesMarker.cs

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Marker class used to track whether core durable task services have been registered.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Problem it solves:</b> Users may call configuration methods multiple times:
+/// <code>
+/// services.ConfigureDurableOptions(...);     // 1st call - registers agent A
+/// services.ConfigureDurableOptions(...);     // 2nd call - registers workflow X
+/// services.ConfigureDurableOptions(...);     // 3rd call - registers agent B and workflow Y
+/// </code>
+/// Each call invokes <c>EnsureDurableServicesRegistered</c>. Without this marker, core services like
+/// <c>AddDurableTaskWorker</c> and <c>AddDurableTaskClient</c> would be registered multiple times,
+/// causing runtime errors or unexpected behavior.
+/// </para>
+/// <para>
+/// <b>How it works:</b>
+/// <list type="number">
+/// <item><description>First call: No marker in services → register marker + all core services</description></item>
+/// <item><description>Subsequent calls: Marker exists → early return, skip core service registration</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// <b>Why not use TryAddSingleton for everything?</b>
+/// While <c>TryAddSingleton</c> prevents duplicate simple service registrations, it doesn't work for
+/// complex registrations like <c>AddDurableTaskWorker</c> which have side effects and configure
+/// internal builders. The marker pattern provides a clean, explicit guard for the entire registration block.
+/// </para>
+/// </remarks>
+internal sealed class DurableServicesMarker;

dotnet/src/Microsoft.Agents.AI.DurableTask/EntityAgentWrapper.cs

@@ -0,0 +1,125 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using Microsoft.Agents.AI;
+using Microsoft.DurableTask.Entities;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+internal sealed class EntityAgentWrapper(
+    AIAgent innerAgent,
+    TaskEntityContext entityContext,
+    RunRequest runRequest,
+    IServiceProvider? entityScopedServices = null) : DelegatingAIAgent(innerAgent)
+{
+    private readonly TaskEntityContext _entityContext = entityContext;
+    private readonly RunRequest _runRequest = runRequest;
+    private readonly IServiceProvider? _entityScopedServices = entityScopedServices;
+
+    // The ID of the agent is always the entity ID.
+    protected override string? IdCore => this._entityContext.Id.ToString();
+
+    protected override async Task<AgentResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        AgentResponse response = await base.RunCoreAsync(
+            messages,
+            session,
+            this.GetAgentEntityRunOptions(options),
+            cancellationToken);
+
+        response.AgentId = this.Id;
+        return response;
+    }
+
+    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        await foreach (AgentResponseUpdate update in base.RunCoreStreamingAsync(
+            messages,
+            session,
+            this.GetAgentEntityRunOptions(options),
+            cancellationToken))
+        {
+            update.AgentId = this.Id;
+            yield return update;
+        }
+    }
+
+    // Override the GetService method to provide entity-scoped services.
+    public override object? GetService(Type serviceType, object? serviceKey = null)
+    {
+        object? result = null;
+        if (this._entityScopedServices is not null)
+        {
+            result = (serviceKey is not null && this._entityScopedServices is IKeyedServiceProvider keyedServiceProvider)
+                ? keyedServiceProvider.GetKeyedService(serviceType, serviceKey)
+                : this._entityScopedServices.GetService(serviceType);
+        }
+
+        return result ?? base.GetService(serviceType, serviceKey);
+    }
+
+    private AgentRunOptions GetAgentEntityRunOptions(AgentRunOptions? options = null)
+    {
+        // Copied/modified from FunctionInvocationDelegatingAgent.cs in microsoft/agent-framework.
+        if (options is null || options.GetType() == typeof(AgentRunOptions))
+        {
+            options = new ChatClientAgentRunOptions();
+        }
+
+        if (options is not ChatClientAgentRunOptions chatAgentRunOptions)
+        {
+            throw new NotSupportedException($"Function Invocation Middleware is only supported without options or with {nameof(ChatClientAgentRunOptions)}.");
+        }
+
+        Func<IChatClient, IChatClient>? originalFactory = chatAgentRunOptions.ChatClientFactory;
+
+        chatAgentRunOptions.ChatClientFactory = chatClient =>
+        {
+            ChatClientBuilder builder = chatClient.AsBuilder();
+            if (originalFactory is not null)
+            {
+                builder.Use(originalFactory);
+            }
+
+            // Update the run options based on the run request.
+            // NOTE: Function middleware can go here if needed in the future.
+            return builder.ConfigureOptions(
+                newOptions =>
+                {
+                    // Update the response format if requested by the caller.
+                    if (this._runRequest.ResponseFormat is not null)
+                    {
+                        newOptions.ResponseFormat = this._runRequest.ResponseFormat;
+                    }
+
+                    // Update the tools if requested by the caller.
+                    if (this._runRequest.EnableToolCalls)
+                    {
+                        IList<AITool>? tools = chatAgentRunOptions.ChatOptions?.Tools;
+                        if (tools is not null && this._runRequest.EnableToolNames?.Count > 0)
+                        {
+                            // Filter tools to only include those with matching names
+                            newOptions.Tools = [.. tools.Where(tool => this._runRequest.EnableToolNames.Contains(tool.Name))];
+                        }
+                    }
+                    else
+                    {
+                        newOptions.Tools = null;
+                    }
+                })
+                .Build();
+        };
+
+        return options;
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/IAgentResponseHandler.cs

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Handler for processing responses from the agent. This is typically used to send messages to the user.
+/// </summary>
+public interface IAgentResponseHandler
+{
+    /// <summary>
+    /// Handles a streaming response update from the agent. This is typically used to send messages to the user.
+    /// </summary>
+    /// <param name="messageStream">
+    /// The stream of messages from the agent.
+    /// </param>
+    /// <param name="cancellationToken">
+    /// Signals that the operation should be cancelled.
+    /// </param>
+    ValueTask OnStreamingResponseUpdateAsync(
+        IAsyncEnumerable<AgentResponseUpdate> messageStream,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Handles a discrete response from the agent. This is typically used to send messages to the user.
+    /// </summary>
+    /// <param name="message">
+    /// The message from the agent.
+    /// </param>
+    /// <param name="cancellationToken">
+    /// Signals that the operation should be cancelled.
+    /// </param>
+    ValueTask OnAgentResponseAsync(
+        AgentResponse message,
+        CancellationToken cancellationToken);
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/IDurableAgentClient.cs

@@ -0,0 +1,21 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Represents a client for interacting with a durable agent.
+/// </summary>
+internal interface IDurableAgentClient
+{
+    /// <summary>
+    /// Runs an agent with the specified request.
+    /// </summary>
+    /// <param name="sessionId">The ID of the target agent session.</param>
+    /// <param name="request">The request containing the message, role, and configuration.</param>
+    /// <param name="cancellationToken">The cancellation token for scheduling the request.</param>
+    /// <returns>A task that returns a handle used to read the agent response.</returns>
+    Task<AgentRunHandle> RunAgentAsync(
+        AgentSessionId sessionId,
+        RunRequest request,
+        CancellationToken cancellationToken = default);
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Logs.cs

@@ -0,0 +1,230 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.DurableTask;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Logging;
+
+internal static partial class Logs
+{
+    [LoggerMessage(
+        EventId = 1,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] Request: [{Role}] {Content}")]
+    public static partial void LogAgentRequest(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        ChatRole role,
+        string content);
+
+    [LoggerMessage(
+        EventId = 2,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] Response: [{Role}] {Content} (Input tokens: {InputTokenCount}, Output tokens: {OutputTokenCount}, Total tokens: {TotalTokenCount})")]
+    public static partial void LogAgentResponse(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        ChatRole role,
+        string content,
+        long? inputTokenCount,
+        long? outputTokenCount,
+        long? totalTokenCount);
+
+    [LoggerMessage(
+        EventId = 3,
+        Level = LogLevel.Information,
+        Message = "Signalling agent with session ID '{SessionId}'")]
+    public static partial void LogSignallingAgent(this ILogger logger, AgentSessionId sessionId);
+
+    [LoggerMessage(
+        EventId = 4,
+        Level = LogLevel.Information,
+        Message = "Polling agent with session ID '{SessionId}' for response with correlation ID '{CorrelationId}'")]
+    public static partial void LogStartPollingForResponse(this ILogger logger, AgentSessionId sessionId, string correlationId);
+
+    [LoggerMessage(
+        EventId = 5,
+        Level = LogLevel.Information,
+        Message = "Found response for agent with session ID '{SessionId}' with correlation ID '{CorrelationId}'")]
+    public static partial void LogDonePollingForResponse(this ILogger logger, AgentSessionId sessionId, string correlationId);
+
+    [LoggerMessage(
+        EventId = 6,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] TTL expiration time updated to {ExpirationTime:O}")]
+    public static partial void LogTTLExpirationTimeUpdated(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        DateTime expirationTime);
+
+    [LoggerMessage(
+        EventId = 7,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] TTL deletion signal scheduled for {ScheduledTime:O}")]
+    public static partial void LogTTLDeletionScheduled(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        DateTime scheduledTime);
+
+    [LoggerMessage(
+        EventId = 8,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] TTL deletion check running. Expiration time: {ExpirationTime:O}, Current time: {CurrentTime:O}")]
+    public static partial void LogTTLDeletionCheck(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        DateTime? expirationTime,
+        DateTime currentTime);
+
+    [LoggerMessage(
+        EventId = 9,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] Entity expired and deleted due to TTL. Expiration time: {ExpirationTime:O}")]
+    public static partial void LogTTLEntityExpired(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        DateTime expirationTime);
+
+    [LoggerMessage(
+        EventId = 10,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] TTL deletion signal rescheduled for {ScheduledTime:O}")]
+    public static partial void LogTTLRescheduled(
+        this ILogger logger,
+        AgentSessionId sessionId,
+        DateTime scheduledTime);
+
+    [LoggerMessage(
+        EventId = 11,
+        Level = LogLevel.Information,
+        Message = "[{SessionId}] TTL expiration time cleared (TTL disabled)")]
+    public static partial void LogTTLExpirationTimeCleared(
+        this ILogger logger,
+        AgentSessionId sessionId);
+
+    // Durable workflow logs (EventIds 100-199)
+
+    [LoggerMessage(
+        EventId = 100,
+        Level = LogLevel.Information,
+        Message = "Starting workflow '{WorkflowName}' with instance '{InstanceId}'")]
+    public static partial void LogWorkflowStarting(
+        this ILogger logger,
+        string workflowName,
+        string instanceId);
+
+    [LoggerMessage(
+        EventId = 101,
+        Level = LogLevel.Information,
+        Message = "Superstep {Step}: {Count} active executor(s)")]
+    public static partial void LogSuperstepStarting(
+        this ILogger logger,
+        int step,
+        int count);
+
+    [LoggerMessage(
+        EventId = 102,
+        Level = LogLevel.Debug,
+        Message = "Superstep {Step} executors: [{Executors}]")]
+    public static partial void LogSuperstepExecutors(
+        this ILogger logger,
+        int step,
+        string executors);
+
+    [LoggerMessage(
+        EventId = 103,
+        Level = LogLevel.Information,
+        Message = "Workflow completed")]
+    public static partial void LogWorkflowCompleted(
+        this ILogger logger);
+
+    [LoggerMessage(
+        EventId = 104,
+        Level = LogLevel.Warning,
+        Message = "Workflow '{InstanceId}' terminated early: reached maximum superstep limit ({MaxSupersteps}) with {RemainingExecutors} executor(s) still queued")]
+    public static partial void LogWorkflowMaxSuperstepsExceeded(
+        this ILogger logger,
+        string instanceId,
+        int maxSupersteps,
+        int remainingExecutors);
+
+    [LoggerMessage(
+        EventId = 105,
+        Level = LogLevel.Debug,
+        Message = "Fan-In executor {ExecutorId}: aggregated {Count} messages from [{Sources}]")]
+    public static partial void LogFanInAggregated(
+        this ILogger logger,
+        string executorId,
+        int count,
+        string sources);
+
+    [LoggerMessage(
+        EventId = 106,
+        Level = LogLevel.Debug,
+        Message = "Executor '{ExecutorId}' returned result (length: {Length}, messages: {MessageCount})")]
+    public static partial void LogExecutorResultReceived(
+        this ILogger logger,
+        string executorId,
+        int length,
+        int messageCount);
+
+    [LoggerMessage(
+        EventId = 107,
+        Level = LogLevel.Debug,
+        Message = "Dispatching executor '{ExecutorId}' (agentic: {IsAgentic})")]
+    public static partial void LogDispatchingExecutor(
+        this ILogger logger,
+        string executorId,
+        bool isAgentic);
+
+    [LoggerMessage(
+        EventId = 108,
+        Level = LogLevel.Warning,
+        Message = "Agent '{AgentName}' not found")]
+    public static partial void LogAgentNotFound(
+        this ILogger logger,
+        string agentName);
+
+    [LoggerMessage(
+        EventId = 109,
+        Level = LogLevel.Debug,
+        Message = "Edge {Source} -> {Sink}: condition returned false, skipping")]
+    public static partial void LogEdgeConditionFalse(
+        this ILogger logger,
+        string source,
+        string sink);
+
+    [LoggerMessage(
+        EventId = 110,
+        Level = LogLevel.Warning,
+        Message = "Failed to evaluate condition for edge {Source} -> {Sink}, skipping")]
+    public static partial void LogEdgeConditionEvaluationFailed(
+        this ILogger logger,
+        Exception ex,
+        string source,
+        string sink);
+
+    [LoggerMessage(
+        EventId = 111,
+        Level = LogLevel.Debug,
+        Message = "Edge {Source} -> {Sink}: routing message")]
+    public static partial void LogEdgeRoutingMessage(
+        this ILogger logger,
+        string source,
+        string sink);
+
+    [LoggerMessage(
+        EventId = 112,
+        Level = LogLevel.Information,
+        Message = "Workflow waiting for external input at RequestPort '{RequestPortId}'")]
+    public static partial void LogWaitingForExternalEvent(
+        this ILogger logger,
+        string requestPortId);
+
+    [LoggerMessage(
+        EventId = 113,
+        Level = LogLevel.Information,
+        Message = "Received external event for RequestPort '{RequestPortId}'")]
+    public static partial void LogReceivedExternalEvent(
+        this ILogger logger,
+        string requestPortId);
+}

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

@@ -0,0 +1,43 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <!-- CA2007: This rule should generally be suppressed in Durable Task libraries -->
+    <NoWarn>$(NoWarn);CA2007</NoWarn>
+  </PropertyGroup>
+
+  <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
+
+  <!-- NuGet package metadata -->
+  <PropertyGroup>
+    <Title>Durable Task extensions for Microsoft Agent Framework</Title>
+    <Description>Provides distributed durable execution capabilities for agents built with Microsoft Agent Framework.</Description>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectSharedStructuredOutput>true</InjectSharedStructuredOutput>
+  </PropertyGroup>
+  
+  <!-- Durable Task dependencies -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.DurableTask.Client" />
+    <PackageReference Include="Microsoft.DurableTask.Worker" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <InternalsVisibleTo Include="Microsoft.Agents.AI.DurableTask.IntegrationTests" />
+    <InternalsVisibleTo Include="Microsoft.Agents.AI.DurableTask.UnitTests" />
+    <InternalsVisibleTo Include="Microsoft.Agents.AI.Hosting.AzureFunctions" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath="/" />
+  </ItemGroup>
+</Project>

dotnet/src/Microsoft.Agents.AI.DurableTask/README.md

@@ -0,0 +1,42 @@
+# Microsoft.Agents.AI.DurableTask
+
+The Microsoft Agent Framework provides a programming model for building agents and agent workflows in .NET. This package, the *Durable Task extension for the Agent Framework*, extends the Agent Framework programming model with the following capabilities:
+
+- Stateful, durable execution of agents in distributed environments
+- Automatic conversation history management
+- Long-running agent workflows as "durable orchestrator" functions
+- Tools and dashboards for managing and monitoring agents and agent workflows
+
+These capabilities are implemented using foundational technologies from the Durable Task technology stack:
+
+- [Durable Entities](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-entities) for stateful, durable execution of agents
+- [Durable Orchestrations](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-orchestrations) for long-running agent workflows
+- The [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/choose-orchestration-framework) for managing durable task execution and observability at scale
+
+This package can be used by itself or in conjunction with the `Microsoft.Agents.AI.Hosting.AzureFunctions` package, which provides additional features via Azure Functions integration.
+
+## Install the package
+
+From the command-line:
+
+```bash
+dotnet add package Microsoft.Agents.AI.DurableTask
+```
+
+Or directly in your project file:
+
+```xml
+<ItemGroup>
+  <PackageReference Include="Microsoft.Agents.AI.DurableTask" Version="[CURRENTVERSION]" />
+</ItemGroup>
+```
+
+You can alternatively just reference the `Microsoft.Agents.AI.Hosting.AzureFunctions` package if you're hosting your agents and orchestrations in the Azure Functions .NET Isolated worker.
+
+## Usage Examples
+
+For a comprehensive tour of all the functionality, concepts, and APIs, check out the [Azure Functions samples](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/).
+
+## Feedback & Contributing
+
+We welcome feedback and contributions in [our GitHub repo](https://github.com/microsoft/agent-framework).

dotnet/src/Microsoft.Agents.AI.DurableTask/RunRequest.cs

@@ -0,0 +1,83 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Represents a request to run an agent with a specific message and configuration.
+/// </summary>
+public record RunRequest
+{
+    /// <summary>
+    /// Gets the list of chat messages to send to the agent (for multi-message requests).
+    /// </summary>
+    public IList<ChatMessage> Messages { get; init; } = [];
+
+    /// <summary>
+    /// Gets the optional response format for the agent's response.
+    /// </summary>
+    public ChatResponseFormat? ResponseFormat { get; init; }
+
+    /// <summary>
+    /// Gets whether to enable tool calls for this request.
+    /// </summary>
+    public bool EnableToolCalls { get; init; } = true;
+
+    /// <summary>
+    /// Gets the collection of tool names to enable. If not specified, all tools are enabled.
+    /// </summary>
+    public IList<string>? EnableToolNames { get; init; }
+
+    /// <summary>
+    /// Gets or sets the correlation ID for correlating this request with its response.
+    /// </summary>
+    [JsonInclude]
+    internal string CorrelationId { get; set; } = Guid.NewGuid().ToString("N");
+
+    /// <summary>
+    /// Gets or sets the ID of the orchestration that initiated this request (if any).
+    /// </summary>
+    [JsonInclude]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    internal string? OrchestrationId { get; set; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="RunRequest"/> class for a single message.
+    /// </summary>
+    /// <param name="message">The message to send to the agent.</param>
+    /// <param name="role">The role of the message sender (User or System).</param>
+    /// <param name="responseFormat">Optional response format for the agent's response.</param>
+    /// <param name="enableToolCalls">Whether to enable tool calls for this request.</param>
+    /// <param name="enableToolNames">Optional collection of tool names to enable. If not specified, all tools are enabled.</param>
+    public RunRequest(
+        string message,
+        ChatRole? role = null,
+        ChatResponseFormat? responseFormat = null,
+        bool enableToolCalls = true,
+        IList<string>? enableToolNames = null)
+        : this([new ChatMessage(role ?? ChatRole.User, message) { CreatedAt = DateTimeOffset.UtcNow }], responseFormat, enableToolCalls, enableToolNames)
+    {
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="RunRequest"/> class for multiple messages.
+    /// </summary>
+    /// <param name="messages">The list of chat messages to send to the agent.</param>
+    /// <param name="responseFormat">Optional response format for the agent's response.</param>
+    /// <param name="enableToolCalls">Whether to enable tool calls for this request.</param>
+    /// <param name="enableToolNames">Optional collection of tool names to enable. If not specified, all tools are enabled.</param>
+    [JsonConstructor]
+    public RunRequest(
+        IList<ChatMessage> messages,
+        ChatResponseFormat? responseFormat = null,
+        bool enableToolCalls = true,
+        IList<string>? enableToolNames = null)
+    {
+        this.Messages = messages;
+        this.ResponseFormat = responseFormat;
+        this.EnableToolCalls = enableToolCalls;
+        this.EnableToolNames = enableToolNames;
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/ServiceCollectionExtensions.cs

@@ -0,0 +1,381 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.DurableTask.Workflows;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask;
+using Microsoft.DurableTask.Client;
+using Microsoft.DurableTask.Worker;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.DependencyInjection.Extensions;
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Extension methods for configuring durable agents and workflows with dependency injection.
+/// </summary>
+public static class ServiceCollectionExtensions
+{
+    /// <summary>
+    /// Gets a durable agent proxy by name.
+    /// </summary>
+    /// <param name="services">The service provider.</param>
+    /// <param name="name">The name of the agent.</param>
+    /// <returns>The durable agent proxy.</returns>
+    /// <exception cref="KeyNotFoundException">Thrown if the agent proxy is not found.</exception>
+    public static AIAgent GetDurableAgentProxy(this IServiceProvider services, string name)
+    {
+        return services.GetKeyedService<AIAgent>(name)
+            ?? throw new KeyNotFoundException($"A durable agent with name '{name}' has not been registered.");
+    }
+
+    /// <summary>
+    /// Configures durable agents, automatically registering agent entities.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This method provides an agent-focused configuration experience.
+    /// If you need to configure both agents and workflows, consider using
+    /// <see cref="ConfigureDurableOptions"/> instead.
+    /// </para>
+    /// <para>
+    /// Multiple calls to this method are supported and configurations are composed additively.
+    /// </para>
+    /// </remarks>
+    /// <param name="services">The service collection.</param>
+    /// <param name="configure">A delegate to configure the durable agents.</param>
+    /// <param name="workerBuilder">Optional delegate to configure the Durable Task worker.</param>
+    /// <param name="clientBuilder">Optional delegate to configure the Durable Task client.</param>
+    /// <returns>The service collection for chaining.</returns>
+    public static IServiceCollection ConfigureDurableAgents(
+        this IServiceCollection services,
+        Action<DurableAgentsOptions> configure,
+        Action<IDurableTaskWorkerBuilder>? workerBuilder = null,
+        Action<IDurableTaskClientBuilder>? clientBuilder = null)
+    {
+        return services.ConfigureDurableOptions(
+            options => configure(options.Agents),
+            workerBuilder,
+            clientBuilder);
+    }
+
+    /// <summary>
+    /// Configures durable workflows, automatically registering orchestrations and activities.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This method provides a workflow-focused configuration experience.
+    /// If you need to configure both agents and workflows, consider using
+    /// <see cref="ConfigureDurableOptions"/> instead.
+    /// </para>
+    /// <para>
+    /// Multiple calls to this method are supported and configurations are composed additively.
+    /// </para>
+    /// </remarks>
+    /// <param name="services">The service collection to configure.</param>
+    /// <param name="configure">A delegate to configure the workflow options.</param>
+    /// <param name="workerBuilder">Optional delegate to configure the durable task worker.</param>
+    /// <param name="clientBuilder">Optional delegate to configure the durable task client.</param>
+    /// <returns>The service collection for chaining.</returns>
+    public static IServiceCollection ConfigureDurableWorkflows(
+        this IServiceCollection services,
+        Action<DurableWorkflowOptions> configure,
+        Action<IDurableTaskWorkerBuilder>? workerBuilder = null,
+        Action<IDurableTaskClientBuilder>? clientBuilder = null)
+    {
+        return services.ConfigureDurableOptions(
+            options => configure(options.Workflows),
+            workerBuilder,
+            clientBuilder);
+    }
+
+    /// <summary>
+    /// Configures durable agents and workflows, automatically registering orchestrations, activities, and agent entities.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This is the recommended entry point for configuring durable functionality. It provides unified configuration
+    /// for both agents and workflows through a single <see cref="DurableOptions"/> instance, ensuring agents
+    /// referenced in workflows are automatically registered.
+    /// </para>
+    /// <para>
+    /// Multiple calls to this method (or to <see cref="ConfigureDurableAgents"/>
+    /// and <see cref="ConfigureDurableWorkflows"/>) are supported and configurations are composed additively.
+    /// </para>
+    /// </remarks>
+    /// <param name="services">The service collection to configure.</param>
+    /// <param name="configure">A delegate to configure the durable options for both agents and workflows.</param>
+    /// <param name="workerBuilder">Optional delegate to configure the durable task worker.</param>
+    /// <param name="clientBuilder">Optional delegate to configure the durable task client.</param>
+    /// <returns>The service collection for chaining.</returns>
+    /// <example>
+    /// <code>
+    /// services.ConfigureDurableOptions(options =>
+    /// {
+    ///     // Register agents not part of workflows
+    ///     options.Agents.AddAIAgent(standaloneAgent);
+    ///
+    ///     // Register workflows - agents in workflows are auto-registered
+    ///     options.Workflows.AddWorkflow(myWorkflow);
+    /// },
+    /// workerBuilder: builder => builder.UseDurableTaskScheduler(connectionString),
+    /// clientBuilder: builder => builder.UseDurableTaskScheduler(connectionString));
+    /// </code>
+    /// </example>
+    public static IServiceCollection ConfigureDurableOptions(
+        this IServiceCollection services,
+        Action<DurableOptions> configure,
+        Action<IDurableTaskWorkerBuilder>? workerBuilder = null,
+        Action<IDurableTaskClientBuilder>? clientBuilder = null)
+    {
+        ArgumentNullException.ThrowIfNull(services);
+        ArgumentNullException.ThrowIfNull(configure);
+
+        // Get or create the shared DurableOptions instance for configuration
+        DurableOptions sharedOptions = GetOrCreateSharedOptions(services);
+
+        // Apply the configuration immediately to capture agent names for keyed service registration
+        configure(sharedOptions);
+
+        // Register keyed services for any new agents
+        RegisterAgentKeyedServices(services, sharedOptions);
+
+        // Register core services only once
+        EnsureDurableServicesRegistered(services, sharedOptions, workerBuilder, clientBuilder);
+
+        return services;
+    }
+
+    private static DurableOptions GetOrCreateSharedOptions(IServiceCollection services)
+    {
+        // Look for an existing DurableOptions registration
+        ServiceDescriptor? existingDescriptor = services.FirstOrDefault(
+            d => d.ServiceType == typeof(DurableOptions) && d.ImplementationInstance is not null);
+
+        if (existingDescriptor?.ImplementationInstance is DurableOptions existing)
+        {
+            return existing;
+        }
+
+        // Create a new shared options instance
+        DurableOptions options = new();
+        services.AddSingleton(options);
+        return options;
+    }
+
+    private static void RegisterAgentKeyedServices(IServiceCollection services, DurableOptions options)
+    {
+        foreach (KeyValuePair<string, Func<IServiceProvider, AIAgent>> factory in options.Agents.GetAgentFactories())
+        {
+            // Only add if not already registered (to support multiple Configure* calls)
+            if (!services.Any(d => d.ServiceType == typeof(AIAgent) && d.IsKeyedService && Equals(d.ServiceKey, factory.Key)))
+            {
+                services.AddKeyedSingleton(factory.Key, (sp, _) => factory.Value(sp).AsDurableAgentProxy(sp));
+            }
+        }
+    }
+
+    /// <summary>
+    /// Ensures that the core durable services are registered only once, regardless of how many
+    /// times the configuration methods are called.
+    /// </summary>
+    private static void EnsureDurableServicesRegistered(
+        IServiceCollection services,
+        DurableOptions sharedOptions,
+        Action<IDurableTaskWorkerBuilder>? workerBuilder,
+        Action<IDurableTaskClientBuilder>? clientBuilder)
+    {
+        // Use a marker to ensure we only register core services once
+        if (services.Any(d => d.ServiceType == typeof(DurableServicesMarker)))
+        {
+            return;
+        }
+
+        services.AddSingleton<DurableServicesMarker>();
+
+        services.TryAddSingleton<DurableWorkflowRunner>();
+
+        // Configure Durable Task Worker - capture sharedOptions reference in closure.
+        // The options object is populated by all Configure* calls before the worker starts.
+
+        if (workerBuilder is not null)
+        {
+            services.AddDurableTaskWorker(builder =>
+            {
+                workerBuilder?.Invoke(builder);
+
+                builder.AddTasks(registry => RegisterTasksFromOptions(registry, sharedOptions));
+            });
+        }
+
+        // Configure Durable Task Client
+        if (clientBuilder is not null)
+        {
+            services.AddDurableTaskClient(clientBuilder);
+            services.TryAddSingleton<IWorkflowClient, DurableWorkflowClient>();
+            services.TryAddSingleton<IDurableAgentClient, DefaultDurableAgentClient>();
+        }
+
+        // Register workflow and agent services
+        services.TryAddSingleton<DataConverter, DurableDataConverter>();
+
+        // Register agent factories resolver - returns factories from the shared options
+        services.TryAddSingleton(
+            sp => sp.GetRequiredService<DurableOptions>().Agents.GetAgentFactories());
+
+        // Register DurableAgentsOptions resolver
+        services.TryAddSingleton(sp => sp.GetRequiredService<DurableOptions>().Agents);
+    }
+
+    private static void RegisterTasksFromOptions(DurableTaskRegistry registry, DurableOptions durableOptions)
+    {
+        // Build registrations for all workflows including sub-workflows
+        List<WorkflowRegistrationInfo> registrations = [];
+        HashSet<string> registeredActivities = [];
+        HashSet<string> registeredOrchestrations = [];
+
+        DurableWorkflowOptions workflowOptions = durableOptions.Workflows;
+        foreach (Workflow workflow in workflowOptions.Workflows.Values.ToList())
+        {
+            BuildWorkflowRegistrationRecursive(
+                workflow,
+                workflowOptions,
+                registrations,
+                registeredActivities,
+                registeredOrchestrations);
+        }
+
+        IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>> agentFactories =
+            durableOptions.Agents.GetAgentFactories();
+
+        // Register orchestrations and activities
+        foreach (WorkflowRegistrationInfo registration in registrations)
+        {
+            // Register with DurableWorkflowInput<object> - the DataConverter handles serialization/deserialization
+            registry.AddOrchestratorFunc<DurableWorkflowInput<object>, DurableWorkflowResult>(
+                registration.OrchestrationName,
+                (context, input) => RunWorkflowOrchestrationAsync(context, input, durableOptions));
+
+            foreach (ActivityRegistrationInfo activity in registration.Activities)
+            {
+                ExecutorBinding binding = activity.Binding;
+                registry.AddActivityFunc<string, string>(
+                    activity.ActivityName,
+                (context, input) => DurableActivityExecutor.ExecuteAsync(binding, input));
+            }
+        }
+
+        // Register agent entities
+        foreach (string agentName in agentFactories.Keys)
+        {
+            registry.AddEntity<AgentEntity>(AgentSessionId.ToEntityName(agentName));
+        }
+    }
+
+    private static void BuildWorkflowRegistrationRecursive(
+        Workflow workflow,
+        DurableWorkflowOptions workflowOptions,
+        List<WorkflowRegistrationInfo> registrations,
+        HashSet<string> registeredActivities,
+        HashSet<string> registeredOrchestrations)
+    {
+        string orchestrationName = WorkflowNamingHelper.ToOrchestrationFunctionName(workflow.Name!);
+
+        if (!registeredOrchestrations.Add(orchestrationName))
+        {
+            return;
+        }
+
+        registrations.Add(BuildWorkflowRegistration(workflow, registeredActivities));
+
+        // Process subworkflows recursively to register them as separate orchestrations
+        foreach (SubworkflowBinding subworkflowBinding in workflow.ReflectExecutors()
+            .Select(e => e.Value)
+            .OfType<SubworkflowBinding>())
+        {
+            Workflow subWorkflow = subworkflowBinding.WorkflowInstance;
+            workflowOptions.AddWorkflow(subWorkflow);
+
+            BuildWorkflowRegistrationRecursive(
+                subWorkflow,
+                workflowOptions,
+                registrations,
+                registeredActivities,
+                registeredOrchestrations);
+        }
+    }
+
+    private static WorkflowRegistrationInfo BuildWorkflowRegistration(
+        Workflow workflow,
+        HashSet<string> registeredActivities)
+    {
+        string orchestrationName = WorkflowNamingHelper.ToOrchestrationFunctionName(workflow.Name!);
+        Dictionary<string, ExecutorBinding> executorBindings = workflow.ReflectExecutors();
+        List<ActivityRegistrationInfo> activities = [];
+
+        foreach (KeyValuePair<string, ExecutorBinding> entry in executorBindings
+                    .Where(e => IsActivityBinding(e.Value)))
+        {
+            string executorName = WorkflowNamingHelper.GetExecutorName(entry.Key);
+            string activityName = WorkflowNamingHelper.ToOrchestrationFunctionName(executorName);
+
+            if (registeredActivities.Add(activityName))
+            {
+                activities.Add(new ActivityRegistrationInfo(activityName, entry.Value));
+            }
+        }
+
+        return new WorkflowRegistrationInfo(orchestrationName, activities);
+    }
+
+    /// <summary>
+    /// Returns <see langword="true"/> for bindings that should be registered as Durable Task activities.
+    /// <see cref="AIAgentBinding"/> (Durable Entities), <see cref="SubworkflowBinding"/> (sub-orchestrations),
+    /// and <see cref="RequestPortBinding"/> (human-in-the-loop via external events) use specialized dispatch
+    /// and are excluded.
+    /// </summary>
+    private static bool IsActivityBinding(ExecutorBinding binding)
+        => binding is not AIAgentBinding
+            and not SubworkflowBinding
+            and not RequestPortBinding;
+
+    private static async Task<DurableWorkflowResult> RunWorkflowOrchestrationAsync(
+        TaskOrchestrationContext context,
+        DurableWorkflowInput<object> workflowInput,
+        DurableOptions durableOptions)
+    {
+        ILogger logger = context.CreateReplaySafeLogger("DurableWorkflow");
+        DurableWorkflowRunner runner = new(durableOptions);
+
+        // ConfigureAwait(true) is required in orchestration code for deterministic replay.
+        return await runner.RunWorkflowOrchestrationAsync(context, workflowInput, logger).ConfigureAwait(true);
+    }
+
+    private sealed record WorkflowRegistrationInfo(string OrchestrationName, List<ActivityRegistrationInfo> Activities);
+
+    private sealed record ActivityRegistrationInfo(string ActivityName, ExecutorBinding Binding);
+
+    /// <summary>
+    /// Validates that an agent with the specified name has been registered.
+    /// </summary>
+    /// <param name="services">The service provider.</param>
+    /// <param name="agentName">The name of the agent to validate.</param>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when the agent dictionary is not registered in the service provider.
+    /// </exception>
+    /// <exception cref="AgentNotRegisteredException">
+    /// Thrown when the agent with the specified name has not been registered.
+    /// </exception>
+    internal static void ValidateAgentIsRegistered(IServiceProvider services, string agentName)
+    {
+        IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>>? agents =
+            services.GetService<IReadOnlyDictionary<string, Func<IServiceProvider, AIAgent>>>()
+            ?? throw new InvalidOperationException(
+                $"Durable agents have not been configured. Ensure {nameof(ConfigureDurableAgents)} has been called on the service collection.");
+
+        if (!agents.ContainsKey(agentName))
+        {
+            throw new AgentNotRegisteredException(agentName);
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentState.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents the state of a durable agent, including its conversation history.
+/// </summary>
+[JsonConverter(typeof(DurableAgentStateJsonConverter))]
+internal sealed class DurableAgentState
+{
+    /// <summary>
+    /// Gets the data of the durable agent.
+    /// </summary>
+    [JsonPropertyName("data")]
+    public DurableAgentStateData Data { get; init; } = new();
+
+    /// <summary>
+    /// Gets the schema version of the durable agent state.
+    /// </summary>
+    /// <remarks>
+    /// The version is specified in semver (i.e. "major.minor.patch") format.
+    /// </remarks>
+    [JsonPropertyName("schemaVersion")]
+    public string SchemaVersion { get; init; } = "1.1.0";
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateContent.cs

@@ -0,0 +1,60 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Base class for durable agent state content types.
+/// </summary>
+[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
+[JsonDerivedType(typeof(DurableAgentStateDataContent), "data")]
+[JsonDerivedType(typeof(DurableAgentStateErrorContent), "error")]
+[JsonDerivedType(typeof(DurableAgentStateFunctionCallContent), "functionCall")]
+[JsonDerivedType(typeof(DurableAgentStateFunctionResultContent), "functionResult")]
+[JsonDerivedType(typeof(DurableAgentStateHostedFileContent), "hostedFile")]
+[JsonDerivedType(typeof(DurableAgentStateHostedVectorStoreContent), "hostedVectorStore")]
+[JsonDerivedType(typeof(DurableAgentStateTextContent), "text")]
+[JsonDerivedType(typeof(DurableAgentStateTextReasoningContent), "reasoning")]
+[JsonDerivedType(typeof(DurableAgentStateUriContent), "uri")]
+[JsonDerivedType(typeof(DurableAgentStateUsageContent), "usage")]
+[JsonDerivedType(typeof(DurableAgentStateUnknownContent), "unknown")]
+internal abstract class DurableAgentStateContent
+{
+    /// <summary>
+    /// Gets any additional data found during deserialization that does not map to known properties.
+    /// </summary>
+    [JsonExtensionData]
+    public IDictionary<string, JsonElement>? ExtensionData { get; set; }
+
+    /// <summary>
+    /// Converts this durable agent state content to an <see cref="AIContent"/>.
+    /// </summary>
+    /// <returns>A converted <see cref="AIContent"/> instance.</returns>
+    public abstract AIContent ToAIContent();
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateContent"/> from an <see cref="AIContent"/>.
+    /// </summary>
+    /// <param name="content">The <see cref="AIContent"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateContent"/> representing the original <see cref="AIContent"/>.</returns>
+    public static DurableAgentStateContent FromAIContent(AIContent content)
+    {
+        return content switch
+        {
+            DataContent dataContent => DurableAgentStateDataContent.FromDataContent(dataContent),
+            ErrorContent errorContent => DurableAgentStateErrorContent.FromErrorContent(errorContent),
+            FunctionCallContent functionCallContent => DurableAgentStateFunctionCallContent.FromFunctionCallContent(functionCallContent),
+            FunctionResultContent functionResultContent => DurableAgentStateFunctionResultContent.FromFunctionResultContent(functionResultContent),
+            HostedFileContent hostedFileContent => DurableAgentStateHostedFileContent.FromHostedFileContent(hostedFileContent),
+            HostedVectorStoreContent hostedVectorStoreContent => DurableAgentStateHostedVectorStoreContent.FromHostedVectorStoreContent(hostedVectorStoreContent),
+            TextContent textContent => DurableAgentStateTextContent.FromTextContent(textContent),
+            TextReasoningContent textReasoningContent => DurableAgentStateTextReasoningContent.FromTextReasoningContent(textReasoningContent),
+            UriContent uriContent => DurableAgentStateUriContent.FromUriContent(uriContent),
+            UsageContent usageContent => DurableAgentStateUsageContent.FromUsageContent(usageContent),
+            _ => DurableAgentStateUnknownContent.FromUnknownContent(content)
+        };
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateData.cs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents the data of a durable agent, including its conversation history.
+/// </summary>
+internal sealed class DurableAgentStateData
+{
+    /// <summary>
+    /// Gets the ordered list of state entries representing the complete conversation history.
+    /// This includes both user messages and agent responses in chronological order.
+    /// </summary>
+    [JsonPropertyName("conversationHistory")]
+    public IList<DurableAgentStateEntry> ConversationHistory { get; init; } = [];
+
+    /// <summary>
+    /// Gets or sets the expiration time (UTC) for this agent entity.
+    /// If the entity is idle beyond this time, it will be automatically deleted.
+    /// </summary>
+    [JsonPropertyName("expirationTimeUtc")]
+    public DateTime? ExpirationTimeUtc { get; set; }
+
+    /// <summary>
+    /// Gets any additional data found during deserialization that does not map to known properties.
+    /// </summary>
+    [JsonExtensionData]
+    public IDictionary<string, JsonElement>? ExtensionData { get; set; }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateDataContent.cs

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents a durable agent state content that contains data content.
+/// </summary>
+internal sealed class DurableAgentStateDataContent : DurableAgentStateContent
+{
+    /// <summary>
+    /// Gets the URI of the data content.
+    /// </summary>
+    [JsonPropertyName("uri")]
+    public required string Uri { get; init; }
+
+    /// <summary>
+    /// Gets the media type of the data content.
+    /// </summary>
+    [JsonPropertyName("mediaType")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? MediaType { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateDataContent"/> from a <see cref="DataContent"/>.
+    /// </summary>
+    /// <param name="content">The <see cref="DataContent"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateDataContent"/> representing the original <see cref="DataContent"/>.</returns>
+    public static DurableAgentStateDataContent FromDataContent(DataContent content)
+    {
+        return new DurableAgentStateDataContent()
+        {
+            MediaType = content.MediaType,
+            Uri = content.Uri
+        };
+    }
+
+    /// <inheritdoc/>
+    public override AIContent ToAIContent()
+    {
+        return new DataContent(this.Uri, this.MediaType);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateEntry.cs

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents a single entry in the durable agent state, which can either be a
+/// user/system request or agent response.
+/// </summary>
+[JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
+[JsonDerivedType(typeof(DurableAgentStateRequest), "request")]
+[JsonDerivedType(typeof(DurableAgentStateResponse), "response")]
+internal abstract class DurableAgentStateEntry
+{
+    /// <summary>
+    /// Gets the correlation ID for this entry.
+    /// </summary>
+    /// <remarks>
+    /// This ID is used to correlate <see cref="DurableAgentStateResponse"/> back to its
+    /// <see cref="DurableAgentStateRequest"/>.
+    /// </remarks>
+    [JsonPropertyName("correlationId")]
+    public required string CorrelationId { get; init; }
+
+    /// <summary>
+    /// Gets the timestamp when this entry was created.
+    /// </summary>
+    [JsonPropertyName("createdAt")]
+    public required DateTimeOffset CreatedAt { get; init; }
+
+    /// <summary>
+    /// Gets the list of messages associated with this entry, in chronological order.
+    /// </summary>
+    [JsonPropertyName("messages")]
+    public IReadOnlyList<DurableAgentStateMessage> Messages { get; init; } = [];
+
+    /// <summary>
+    /// Gets any additional data found during deserialization that does not map to known properties.
+    /// </summary>
+    [JsonExtensionData]
+    public IDictionary<string, JsonElement>? ExtensionData { get; set; }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateErrorContent.cs

@@ -0,0 +1,59 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents durable agent state content that contains error content.
+/// </summary>
+internal sealed class DurableAgentStateErrorContent : DurableAgentStateContent
+{
+    /// <summary>
+    /// Gets the error message.
+    /// </summary>
+    [JsonPropertyName("message")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? Message { get; init; }
+
+    /// <summary>
+    /// Gets the error code.
+    /// </summary>
+    [JsonPropertyName("errorCode")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? ErrorCode { get; init; }
+
+    /// <summary>
+    /// Gets the error details.
+    /// </summary>
+    [JsonPropertyName("details")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? Details { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateErrorContent"/> from an <see cref="ErrorContent"/>.
+    /// </summary>
+    /// <param name="content">The <see cref="ErrorContent"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateErrorContent"/> representing the original
+    /// <see cref="ErrorContent"/>.</returns>
+    public static DurableAgentStateErrorContent FromErrorContent(ErrorContent content)
+    {
+        return new DurableAgentStateErrorContent()
+        {
+            Details = content.Details,
+            ErrorCode = content.ErrorCode,
+            Message = content.Message
+        };
+    }
+
+    /// <inheritdoc/>
+    public override AIContent ToAIContent()
+    {
+        return new ErrorContent(this.Message)
+        {
+            Details = this.Details,
+            ErrorCode = this.ErrorCode
+        };
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateFunctionCallContent.cs

@@ -0,0 +1,63 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Immutable;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Durable agent state content representing a function call.
+/// </summary>
+internal sealed class DurableAgentStateFunctionCallContent : DurableAgentStateContent
+{
+    /// <summary>
+    /// The function call arguments.
+    /// </summary>
+    /// TODO: Consider ensuring that empty dictionaries are omitted from serialization.
+    [JsonPropertyName("arguments")]
+    public required IReadOnlyDictionary<string, object?> Arguments { get; init; } =
+        ImmutableDictionary<string, object?>.Empty;
+
+    /// <summary>
+    /// Gets the function call identifier.
+    /// </summary>
+    /// <remarks>
+    /// This is used to correlate this function call with its resulting
+    /// <see cref="DurableAgentStateFunctionResultContent"/>.
+    /// </remarks>
+    [JsonPropertyName("callId")]
+    public required string CallId { get; init; }
+
+    /// <summary>
+    /// Gets the function name.
+    /// </summary>
+    [JsonPropertyName("name")]
+    public required string Name { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateFunctionCallContent"/> from a <see cref="FunctionCallContent"/>.
+    /// </summary>
+    /// <param name="content">The <see cref="FunctionCallContent"/> to convert.</param>
+    /// <returns>
+    /// A <see cref="DurableAgentStateFunctionCallContent"/> representing the original content.
+    /// </returns>
+    public static DurableAgentStateFunctionCallContent FromFunctionCallContent(FunctionCallContent content)
+    {
+        return new DurableAgentStateFunctionCallContent()
+        {
+            Arguments = content.Arguments?.ToDictionary() ?? [],
+            CallId = content.CallId,
+            Name = content.Name
+        };
+    }
+
+    /// <inheritdoc/>
+    public override AIContent ToAIContent()
+    {
+        return new FunctionCallContent(
+            this.CallId,
+            this.Name,
+            new Dictionary<string, object?>(this.Arguments));
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateFunctionResultContent.cs

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents the function result content for a durable agent state response.
+/// </summary>
+internal sealed class DurableAgentStateFunctionResultContent : DurableAgentStateContent
+{
+    /// <summary>
+    /// Gets the function call identifier.
+    /// </summary>
+    /// <remarks>
+    /// This is used to correlate this function result with its originating
+    /// <see cref="DurableAgentStateFunctionCallContent"/>.
+    /// </remarks>
+    [JsonPropertyName("callId")]
+    public required string CallId { get; init; }
+
+    /// <summary>
+    /// Gets the function result.
+    /// </summary>
+    [JsonPropertyName("result")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public object? Result { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateFunctionResultContent"/> from a <see cref="FunctionResultContent"/>.
+    /// </summary>
+    /// <param name="content">The <see cref="FunctionResultContent"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateFunctionResultContent"/> representing the original content.</returns>
+    public static DurableAgentStateFunctionResultContent FromFunctionResultContent(FunctionResultContent content)
+    {
+        return new DurableAgentStateFunctionResultContent()
+        {
+            CallId = content.CallId,
+            Result = content.Result
+        };
+    }
+
+    /// <inheritdoc/>
+    public override AIContent ToAIContent()
+    {
+        return new FunctionResultContent(this.CallId, this.Result);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateHostedFileContent.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents durable agent state content that contains hosted file content.
+/// </summary>
+internal sealed class DurableAgentStateHostedFileContent : DurableAgentStateContent
+{
+    /// <summary>
+    /// Gets the file ID of the hosted file content.
+    /// </summary>
+    [JsonPropertyName("fileId")]
+    public required string FileId { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateHostedFileContent"/> from a <see cref="HostedFileContent"/>.
+    /// </summary>
+    /// <param name="content">The <see cref="HostedFileContent"/> to convert.</param>
+    /// <returns>
+    /// A <see cref="DurableAgentStateHostedFileContent"/> representing the original <see cref="HostedFileContent"/>.
+    /// </returns>
+    public static DurableAgentStateHostedFileContent FromHostedFileContent(HostedFileContent content)
+    {
+        return new DurableAgentStateHostedFileContent()
+        {
+            FileId = content.FileId
+        };
+    }
+
+    /// <inheritdoc/>
+    public override AIContent ToAIContent()
+    {
+        return new HostedFileContent(this.FileId);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateHostedVectorStoreContent.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents durable agent state content that contains hosted vector store content.
+/// </summary>
+internal sealed class DurableAgentStateHostedVectorStoreContent : DurableAgentStateContent
+{
+    /// <summary>
+    /// Gets the vector store ID of the hosted vector store content.
+    /// </summary>
+    [JsonPropertyName("vectorStoreId")]
+    public required string VectorStoreId { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateHostedVectorStoreContent"/> from a <see cref="HostedVectorStoreContent"/>.
+    /// </summary>
+    /// <param name="content">The <see cref="HostedVectorStoreContent"/> to convert.</param>
+    /// <returns>
+    /// A <see cref="DurableAgentStateHostedVectorStoreContent"/> representing the original <see cref="HostedVectorStoreContent"/>.
+    /// </returns>
+    public static DurableAgentStateHostedVectorStoreContent FromHostedVectorStoreContent(HostedVectorStoreContent content)
+    {
+        return new DurableAgentStateHostedVectorStoreContent()
+        {
+            VectorStoreId = content.VectorStoreId
+        };
+    }
+
+    /// <inheritdoc/>
+    public override AIContent ToAIContent()
+    {
+        return new HostedVectorStoreContent(this.VectorStoreId);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateJsonContext.cs

@@ -0,0 +1,40 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+[JsonSourceGenerationOptions(WriteIndented = false)]
+[JsonSerializable(typeof(DurableAgentState))]
+[JsonSerializable(typeof(DurableAgentStateContent))]
+[JsonSerializable(typeof(DurableAgentStateData))]
+[JsonSerializable(typeof(DurableAgentStateEntry))]
+[JsonSerializable(typeof(DurableAgentStateMessage))]
+// Function call and result content
+[JsonSerializable(typeof(Dictionary<string, object>))]
+[JsonSerializable(typeof(IDictionary<string, object?>))]
+[JsonSerializable(typeof(JsonDocument))]
+[JsonSerializable(typeof(JsonElement))]
+[JsonSerializable(typeof(JsonNode))]
+[JsonSerializable(typeof(JsonObject))]
+[JsonSerializable(typeof(JsonValue))]
+[JsonSerializable(typeof(JsonArray))]
+[JsonSerializable(typeof(IEnumerable<string>))]
+[JsonSerializable(typeof(char))]
+[JsonSerializable(typeof(string))]
+[JsonSerializable(typeof(int))]
+[JsonSerializable(typeof(short))]
+[JsonSerializable(typeof(long))]
+[JsonSerializable(typeof(uint))]
+[JsonSerializable(typeof(ushort))]
+[JsonSerializable(typeof(ulong))]
+[JsonSerializable(typeof(float))]
+[JsonSerializable(typeof(double))]
+[JsonSerializable(typeof(decimal))]
+[JsonSerializable(typeof(bool))]
+[JsonSerializable(typeof(TimeSpan))]
+[JsonSerializable(typeof(DateTime))]
+[JsonSerializable(typeof(DateTimeOffset))]
+internal sealed partial class DurableAgentStateJsonContext : JsonSerializerContext;

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateJsonConverter.cs

@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// JSON converter for <see cref="DurableAgentState"/> which performs schema version checks before deserialization.
+/// </summary>
+internal sealed class DurableAgentStateJsonConverter : JsonConverter<DurableAgentState>
+{
+    private const string SchemaVersionPropertyName = "schemaVersion";
+    private const string DataPropertyName = "data";
+
+    /// <inheritdoc/>
+    public override DurableAgentState? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        JsonElement? element = JsonSerializer.Deserialize(
+            ref reader,
+            DurableAgentStateJsonContext.Default.JsonElement);
+
+        if (element is null)
+        {
+            throw new JsonException("The durable agent state is not valid JSON.");
+        }
+
+        if (!element.Value.TryGetProperty(SchemaVersionPropertyName, out JsonElement versionElement))
+        {
+            throw new InvalidOperationException("The durable agent state is missing the 'schemaVersion' property.");
+        }
+
+        if (!Version.TryParse(versionElement.GetString(), out Version? schemaVersion))
+        {
+            throw new InvalidOperationException("The durable agent state has an invalid 'schemaVersion' property.");
+        }
+
+        if (schemaVersion.Major != 1)
+        {
+            throw new InvalidOperationException($"The durable agent state schema version '{schemaVersion}' is not supported.");
+        }
+
+        if (!element.Value.TryGetProperty(DataPropertyName, out JsonElement dataElement))
+        {
+            throw new InvalidOperationException("The durable agent state is missing the 'data' property.");
+        }
+
+        DurableAgentStateData? data = dataElement.Deserialize(
+            DurableAgentStateJsonContext.Default.DurableAgentStateData);
+
+        return new DurableAgentState
+        {
+            SchemaVersion = schemaVersion.ToString(),
+            Data = data ?? new DurableAgentStateData()
+        };
+    }
+
+    /// <inheritdoc/>
+    public override void Write(Utf8JsonWriter writer, DurableAgentState value, JsonSerializerOptions options)
+    {
+        writer.WriteStartObject();
+        writer.WritePropertyName(SchemaVersionPropertyName);
+        writer.WriteStringValue(value.SchemaVersion);
+        writer.WritePropertyName(DataPropertyName);
+        JsonSerializer.Serialize(
+            writer,
+            value.Data,
+            DurableAgentStateJsonContext.Default.DurableAgentStateData);
+        writer.WriteEndObject();
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateMessage.cs

@@ -0,0 +1,76 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents a single message within a durable agent state entry.
+/// </summary>
+internal sealed class DurableAgentStateMessage
+{
+    /// <summary>
+    /// Gets the name of the author of this message.
+    /// </summary>
+    [JsonPropertyName("authorName")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? AuthorName { get; init; }
+
+    /// <summary>
+    /// Gets the timestamp when this message was created.
+    /// </summary>
+    [JsonPropertyName("createdAt")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public DateTimeOffset? CreatedAt { get; init; }
+
+    /// <summary>
+    /// Gets the contents of this message.
+    /// </summary>
+    [JsonPropertyName("contents")]
+    public IReadOnlyList<DurableAgentStateContent> Contents { get; init; } = [];
+
+    /// <summary>
+    /// Gets the role of the message sender (e.g., "user", "assistant", "system").
+    /// </summary>
+    [JsonPropertyName("role")]
+    public required string Role { get; init; }
+
+    /// <summary>
+    /// Gets any additional data found during deserialization that does not map to known properties.
+    /// </summary>
+    [JsonExtensionData]
+    public IDictionary<string, JsonElement>? ExtensionData { get; set; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateMessage"/> from a <see cref="ChatMessage"/>.
+    /// </summary>
+    /// <param name="message">The <see cref="ChatMessage"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateMessage"/> representing the original message.</returns>
+    public static DurableAgentStateMessage FromChatMessage(ChatMessage message)
+    {
+        return new DurableAgentStateMessage()
+        {
+            CreatedAt = message.CreatedAt,
+            AuthorName = message.AuthorName,
+            Role = message.Role.ToString(),
+            Contents = message.Contents.Select(DurableAgentStateContent.FromAIContent).ToList()
+        };
+    }
+
+    /// <summary>
+    /// Converts this <see cref="DurableAgentStateMessage"/> to a <see cref="ChatMessage"/>.
+    /// </summary>
+    /// <returns>A <see cref="ChatMessage"/> representing this message.</returns>
+    public ChatMessage ToChatMessage()
+    {
+        return new ChatMessage()
+        {
+            CreatedAt = this.CreatedAt,
+            AuthorName = this.AuthorName,
+            Contents = this.Contents.Select(c => c.ToAIContent()).ToList(),
+            Role = new(this.Role)
+        };
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateRequest.cs

@@ -0,0 +1,57 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents a user or system request entry in the durable agent state.
+/// </summary>
+internal sealed class DurableAgentStateRequest : DurableAgentStateEntry
+{
+    /// <summary>
+    /// Gets the ID of the orchestration that initiated this request (if any).
+    /// </summary>
+    [JsonPropertyName("orchestrationId")]
+    public string? OrchestrationId { get; init; }
+
+    /// <summary>
+    /// Gets the expected response type for this request (e.g. "json" or "text").
+    /// </summary>
+    /// <remarks>
+    /// If omitted, the expectation is that the agent will respond in plain text.
+    /// </remarks>
+    [JsonPropertyName("responseType")]
+    public string? ResponseType { get; init; }
+
+    /// <summary>
+    /// Gets the expected response JSON schema for this request, if applicable.
+    /// </summary>
+    /// <remarks>
+    /// This is only applicable when <see cref="ResponseType"/> is "json".
+    /// If omitted, no specific schema is expected.
+    /// </remarks>
+    [JsonPropertyName("responseSchema")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public JsonElement? ResponseSchema { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateRequest"/> from a <see cref="RunRequest"/>.
+    /// </summary>
+    /// <param name="request">The <see cref="RunRequest"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateRequest"/> representing the original request.</returns>
+    public static DurableAgentStateRequest FromRunRequest(RunRequest request)
+    {
+        return new DurableAgentStateRequest()
+        {
+            CorrelationId = request.CorrelationId,
+            OrchestrationId = request.OrchestrationId,
+            Messages = request.Messages.Select(DurableAgentStateMessage.FromChatMessage).ToList(),
+            CreatedAt = request.Messages.Min(m => m.CreatedAt) ?? DateTimeOffset.UtcNow,
+            ResponseType = request.ResponseFormat is ChatResponseFormatJson ? "json" : "text",
+            ResponseSchema = (request.ResponseFormat as ChatResponseFormatJson)?.Schema
+        };
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateResponse.cs

@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents a durable agent state entry that is a response from the agent.
+/// </summary>
+internal sealed class DurableAgentStateResponse : DurableAgentStateEntry
+{
+    /// <summary>
+    /// Gets the usage details for this state response.
+    /// </summary>
+    [JsonPropertyName("usage")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public DurableAgentStateUsage? Usage { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateResponse"/> from an <see cref="AgentResponse"/>.
+    /// </summary>
+    /// <param name="correlationId">The correlation ID linking this response to its request.</param>
+    /// <param name="response">The <see cref="AgentResponse"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateResponse"/> representing the original response.</returns>
+    public static DurableAgentStateResponse FromResponse(string correlationId, AgentResponse response)
+    {
+        return new DurableAgentStateResponse()
+        {
+            CorrelationId = correlationId,
+            CreatedAt = response.CreatedAt ?? response.Messages.Max(m => m.CreatedAt) ?? DateTimeOffset.UtcNow,
+            Messages = response.Messages
+                .Where(HasSerializableContent)
+                .Select(DurableAgentStateMessage.FromChatMessage)
+                .ToList(),
+            Usage = DurableAgentStateUsage.FromUsage(response.Usage)
+        };
+    }
+
+    /// <summary>
+    /// Converts this <see cref="DurableAgentStateResponse"/> back to an <see cref="AgentResponse"/>.
+    /// </summary>
+    /// <returns>A <see cref="AgentResponse"/> representing this response.</returns>
+    public AgentResponse ToResponse()
+    {
+        return new AgentResponse()
+        {
+            CreatedAt = this.CreatedAt,
+            Messages = this.Messages.Select(m => m.ToChatMessage()).ToList(),
+            Usage = this.Usage?.ToUsageDetails(),
+        };
+    }
+
+    // Checks whether a ChatMessage has any content that will produce meaningful serialized data.
+    // Known derived AIContent types (TextContent, FunctionCallContent, etc.) are always serializable.
+    // Base AIContent instances only carry RawRepresentation (which is [JsonIgnore]), Annotations, and
+    // AdditionalProperties. We keep the message if any base AIContent has annotations or additional
+    // properties set. NOTE: if AIContent gains new serializable properties in the future, this check
+    // should be updated accordingly.
+    private static bool HasSerializableContent(ChatMessage message)
+    {
+        return message.Contents.Any(c =>
+            c.GetType() != typeof(AIContent) ||
+            c.Annotations?.Count > 0 ||
+            c.AdditionalProperties?.Count > 0);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateTextContent.cs

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents the text content for a durable agent state entry.
+/// </summary>
+internal sealed class DurableAgentStateTextContent : DurableAgentStateContent
+{
+    /// <summary>
+    /// Gets the text message content.
+    /// </summary>
+    [JsonPropertyName("text")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public required string? Text { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateTextContent"/> from a <see cref="TextContent"/>.
+    /// </summary>
+    /// <param name="content">The <see cref="TextContent"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateTextContent"/> representing the original content.</returns>
+    public static DurableAgentStateTextContent FromTextContent(TextContent content)
+    {
+        return new DurableAgentStateTextContent()
+        {
+            Text = content.Text
+        };
+    }
+
+    /// <inheritdoc/>
+    public override AIContent ToAIContent()
+    {
+        return new TextContent(this.Text);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateTextReasoningContent.cs

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents the text reasoning content for a durable agent state entry.
+/// </summary>
+internal sealed class DurableAgentStateTextReasoningContent : DurableAgentStateContent
+{
+    /// <summary>
+    /// Gets the text reasoning content.
+    /// </summary>
+    [JsonPropertyName("text")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public string? Text { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateTextReasoningContent"/> from a <see cref="TextReasoningContent"/>.
+    /// </summary>
+    /// <param name="content">The <see cref="TextReasoningContent"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateTextReasoningContent"/> representing the original content.</returns>
+    public static DurableAgentStateTextReasoningContent FromTextReasoningContent(TextReasoningContent content)
+    {
+        return new DurableAgentStateTextReasoningContent()
+        {
+            Text = content.Text
+        };
+    }
+
+    /// <inheritdoc/>
+    public override AIContent ToAIContent()
+    {
+        return new TextReasoningContent(this.Text);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateUnknownContent.cs

@@ -0,0 +1,43 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents the unknown content for a durable agent state entry.
+/// </summary>
+internal sealed class DurableAgentStateUnknownContent : DurableAgentStateContent
+{
+    /// <summary>
+    /// Gets the serialized unknown content.
+    /// </summary>
+    [JsonPropertyName("content")]
+    public required JsonElement Content { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateUnknownContent"/> from an <see cref="AIContent"/>.
+    /// </summary>
+    /// <param name="content">The <see cref="AIContent"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateUnknownContent"/> representing the original content.</returns>
+    public static DurableAgentStateUnknownContent FromUnknownContent(AIContent content)
+    {
+        return new DurableAgentStateUnknownContent()
+        {
+            Content = JsonSerializer.SerializeToElement(
+                value: content,
+                jsonTypeInfo: AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(AIContent)))
+        };
+    }
+
+    /// <inheritdoc/>
+    public override AIContent ToAIContent()
+    {
+        AIContent? content = this.Content.Deserialize(
+            jsonTypeInfo: AIJsonUtilities.DefaultOptions.GetTypeInfo(typeof(AIContent))) as AIContent;
+
+        return content ?? throw new InvalidOperationException($"The content '{this.Content}' is not valid AI content.");
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateUriContent.cs

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents URI content for a durable agent state message.
+/// </summary>
+internal sealed class DurableAgentStateUriContent : DurableAgentStateContent
+{
+    /// <summary>
+    /// Gets the URI of the content.
+    /// </summary>
+    [JsonPropertyName("uri")]
+    public required Uri Uri { get; init; }
+
+    /// <summary>
+    /// Gets the media type of the content.
+    /// </summary>
+    [JsonPropertyName("mediaType")]
+    public required string MediaType { get; init; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateUriContent"/> from a <see cref="UriContent"/>.
+    /// </summary>
+    /// <param name="uriContent">The <see cref="UriContent"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateUriContent"/> representing the original content.</returns>
+    public static DurableAgentStateUriContent FromUriContent(UriContent uriContent)
+    {
+        return new DurableAgentStateUriContent()
+        {
+            MediaType = uriContent.MediaType,
+            Uri = uriContent.Uri
+        };
+    }
+
+    /// <inheritdoc/>
+    public override AIContent ToAIContent()
+    {
+        return new UriContent(this.Uri, this.MediaType);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateUsage.cs

@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents the token usage details for a durable agent state response.
+/// </summary>
+internal sealed class DurableAgentStateUsage
+{
+    /// <summary>
+    /// Gets the number of input tokens used.
+    /// </summary>
+    [JsonPropertyName("inputTokenCount")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public long? InputTokenCount { get; init; }
+
+    /// <summary>
+    /// Gets the number of output tokens used.
+    /// </summary>
+    [JsonPropertyName("outputTokenCount")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public long? OutputTokenCount { get; init; }
+
+    /// <summary>
+    /// Gets the total number of tokens used.
+    /// </summary>
+    [JsonPropertyName("totalTokenCount")]
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
+    public long? TotalTokenCount { get; init; }
+
+    /// <summary>
+    /// Gets any additional data found during deserialization that does not map to known properties.
+    /// </summary>
+    [JsonExtensionData]
+    public IDictionary<string, JsonElement>? ExtensionData { get; set; }
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateUsage"/> from a <see cref="UsageDetails"/>.
+    /// </summary>
+    /// <param name="usage">The <see cref="UsageDetails"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateUsage"/> representing the original usage details.</returns>
+    [return: NotNullIfNotNull(nameof(usage))]
+    public static DurableAgentStateUsage? FromUsage(UsageDetails? usage) =>
+        usage is not null
+            ? new()
+            {
+                InputTokenCount = usage.InputTokenCount,
+                OutputTokenCount = usage.OutputTokenCount,
+                TotalTokenCount = usage.TotalTokenCount
+            }
+            : null;
+
+    /// <summary>
+    /// Converts this <see cref="DurableAgentStateUsage"/> back to a <see cref="UsageDetails"/>.
+    /// </summary>
+    /// <returns>A <see cref="UsageDetails"/> representing this usage.</returns>
+    public UsageDetails ToUsageDetails()
+    {
+        return new()
+        {
+            InputTokenCount = this.InputTokenCount,
+            OutputTokenCount = this.OutputTokenCount,
+            TotalTokenCount = this.TotalTokenCount
+        };
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/DurableAgentStateUsageContent.cs

@@ -0,0 +1,37 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.DurableTask.State;
+
+/// <summary>
+/// Represents the content for a durable agent state message.
+/// </summary>
+internal sealed class DurableAgentStateUsageContent : DurableAgentStateContent
+{
+    /// <summary>
+    /// Gets the usage details.
+    /// </summary>
+    [JsonPropertyName("usage")]
+    public DurableAgentStateUsage Usage { get; init; } = new();
+
+    /// <summary>
+    /// Creates a <see cref="DurableAgentStateUsageContent"/> from a <see cref="UsageContent"/>.
+    /// </summary>
+    /// <param name="content">The <see cref="UsageContent"/> to convert.</param>
+    /// <returns>A <see cref="DurableAgentStateUsageContent"/> representing the original content.</returns>
+    public static DurableAgentStateUsageContent FromUsageContent(UsageContent content)
+    {
+        return new DurableAgentStateUsageContent()
+        {
+            Usage = DurableAgentStateUsage.FromUsage(content.Details)
+        };
+    }
+
+    /// <inheritdoc/>
+    public override AIContent ToAIContent()
+    {
+        return new UsageContent(this.Usage.ToUsageDetails());
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/State/README.md

@@ -0,0 +1,147 @@
+# Durable Agent State
+
+Durable agents are represented as durable entities, with each session (i.e. thread) of conversation history stored as JSON-serialized state for an individual entity instance.
+
+## State Schema
+
+The [schema](../../../../schemas/durable-agent-entity-state.json) for durable agent state is a distillation of the prompt and response messages accumulated over the lifetime of a session. While these messages and content originate from Microsoft Agent Framework types (for .NET, see [ChatMessage](https://github.com/dotnet/extensions/blob/main/src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatMessage.cs) and [AIContent](https://github.com/dotnet/extensions/blob/main/src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/AIContent.cs)), durable agent state uses its own, parallel, types in order to (1) better manage the versioning and compatibility of serialized state over time, (2) account for agent implementations across languages/platforms (e.g. .NET and Python), as well as (3) ensure consistency for external tools that make use of state data.
+
+> When new AI content types are added to the Microsoft Agent Framework, equivalent types should be added to the entity state schema as well. The durable agent state "unknown" type can be used when an AI content type is encountered but no equivalent type exists.
+
+## State Versioning
+
+The serialized state contains a root `schemaVersion` property, which represents the version of the schema used to serialize data in that state (represented by the `data` property).
+
+Some versioning considerations:
+
+- Versions should use semver notation (e.g. `"<major>.<minor>.<patch>"`)
+- Durable agents should use the version property to determine how to deserialize that state and should not attempt to deserialize semver-incompatible versions
+- Newer versions of durable agents should strive to be compatible with older schema versions (e.g. new properties and objects should be optional)
+- Durable agents should preserve existing, but unrecognized, properties when serializing state
+
+## Sample State
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "data": {
+    "conversationHistory": [
+      {
+        "$type": "request",
+        "responseType": "text",
+        "correlationId": "c338f064f4b44b8d9c21a66e3cda41b2",
+        "createdAt": "2025-11-04T19:33:05.245476+00:00",
+        "messages": [
+          {
+            "contents": [
+              {
+                "$type": "text",
+                "text": "Start the documentation generation workflow for the product \u0027Goldbrew Coffee\u0027"
+              }
+            ],
+            "role": "user"
+          }
+        ]
+      },
+      {
+        "$type": "response",
+        "usage": {
+          "inputTokenCount": 595,
+          "outputTokenCount": 63,
+          "totalTokenCount": 658
+        },
+        "correlationId": "c338f064f4b44b8d9c21a66e3cda41b2",
+        "createdAt": "2025-11-04T19:33:10.47008+00:00",
+        "messages": [
+          {
+            "authorName": "OrchestratorAgent",
+            "createdAt": "2025-11-04T19:33:10+00:00",
+            "contents": [
+              {
+                "$type": "functionCall",
+                "arguments": {
+                  "productName": "Goldbrew Coffee"
+                },
+                "callId": "call_qWk9Ay4doKYrUBoADK8MBwHf",
+                "name": "StartDocumentGeneration"
+              }
+            ],
+            "role": "assistant"
+          },
+          {
+            "authorName": "OrchestratorAgent",
+            "createdAt": "2025-11-04T19:33:10.47008+00:00",
+            "contents": [
+              {
+                "$type": "functionResult",
+                "callId": "call_qWk9Ay4doKYrUBoADK8MBwHf",
+                "result": "8b835e8f2a6f40faabdba33bd8fd8c74"
+              }
+            ],
+            "role": "tool"
+          },
+          {
+            "authorName": "OrchestratorAgent",
+            "createdAt": "2025-11-04T19:33:10+00:00",
+            "contents": [
+              {
+                "$type": "text",
+                "text": "The documentation generation workflow for the product \u0022Goldbrew Coffee\u0022 has been started. You can request updates on its status or provide additional input anytime during the process. Let me know how you\u2019d like to proceed!"
+              }
+            ],
+            "role": "assistant"
+          }
+        ]
+      },
+      {
+        "$type": "request",
+        "responseType": "text",
+        "correlationId": "71f35b7add6b403fadd0db8a7c137b58",
+        "createdAt": "2025-11-04T19:33:11.903413+00:00",
+        "messages": [
+          {
+            "contents": [
+              {
+                "$type": "text",
+                "text": "Tell the user that you\u0027re starting to gather information for product \u0027Goldbrew Coffee\u0027."
+              }
+            ],
+            "role": "system"
+          }
+        ]
+      },
+      {
+        "$type": "response",
+        "usage": {
+          "inputTokenCount": 396,
+          "outputTokenCount": 48,
+          "totalTokenCount": 444
+        },
+        "correlationId": "71f35b7add6b403fadd0db8a7c137b58",
+        "createdAt": "2025-11-04T19:33:12+00:00",
+        "messages": [
+          {
+            "authorName": "OrchestratorAgent",
+            "createdAt": "2025-11-04T19:33:12+00:00",
+            "contents": [
+              {
+                "$type": "text",
+                "text": "I am starting to gather information to create product documentation for \u0027Goldbrew Coffee\u0027. If you have any specific details, key features, or requirements you\u0027d like included, please share them. Otherwise, I\u0027ll continue with the standard documentation process."
+              }
+            ],
+            "role": "assistant"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## State Consumers
+
+Additional tools may make use of durable agent state. Significant changes to the state schema may need corresponding changes to those applications.
+
+### Durable Task Scheduler Dashboard
+
+The [Durable Task Scheduler (DTS)](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler) Dashboard, while providing general UX for management of durable orchestrations and entities, also has UX specific to the use of durable agents.

dotnet/src/Microsoft.Agents.AI.DurableTask/TaskOrchestrationContextExtensions.cs

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using Microsoft.DurableTask;
+
+namespace Microsoft.Agents.AI.DurableTask;
+
+/// <summary>
+/// Agent-related extension methods for the <see cref="TaskOrchestrationContext"/> class.
+/// </summary>
+[EditorBrowsable(EditorBrowsableState.Never)]
+public static class TaskOrchestrationContextExtensions
+{
+    /// <summary>
+    /// Gets a <see cref="DurableAIAgent"/> for interacting with hosted agents within an orchestration.
+    /// </summary>
+    /// <param name="context">The orchestration context.</param>
+    /// <param name="agentName">The name of the agent.</param>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="agentName"/> is null or empty.</exception>
+    /// <returns>A <see cref="DurableAIAgent"/> that can be used to interact with the agent.</returns>
+    public static DurableAIAgent GetAgent(
+        this TaskOrchestrationContext context,
+        string agentName)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(agentName);
+        return new DurableAIAgent(context, agentName);
+    }
+
+    /// <summary>
+    /// Generates an <see cref="AgentSessionId"/> for an agent.
+    /// </summary>
+    /// <remarks>
+    /// This method is deterministic and safe for use in an orchestration context.
+    /// </remarks>
+    /// <param name="context">The orchestration context.</param>
+    /// <param name="agentName">The name of the agent.</param>
+    /// <exception cref="ArgumentException">Thrown when <paramref name="agentName"/> is null or empty.</exception>
+    /// <returns>The generated agent session ID.</returns>
+    internal static AgentSessionId NewAgentSessionId(
+        this TaskOrchestrationContext context,
+        string agentName)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(agentName);
+
+        return new AgentSessionId(agentName, context.NewGuid().ToString("N"));
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableActivityExecutor.cs

@@ -0,0 +1,180 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Agents.AI.Workflows.Checkpointing;
+using Microsoft.Agents.AI.Workflows.Observability;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Executes workflow activities by invoking executor bindings and handling serialization.
+/// </summary>
+[UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Workflow and executor types are registered at startup.")]
+[UnconditionalSuppressMessage("Trimming", "IL2057", Justification = "Workflow and executor types are registered at startup.")]
+[UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Workflow and executor types are registered at startup.")]
+internal static class DurableActivityExecutor
+{
+    /// <summary>
+    /// Executes an activity using the provided executor binding.
+    /// </summary>
+    /// <param name="binding">The executor binding to invoke.</param>
+    /// <param name="input">The serialized input string.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>The serialized activity output.</returns>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="binding"/> is null.</exception>
+    /// <exception cref="InvalidOperationException">Thrown when the executor factory is not configured.</exception>
+    internal static async Task<string> ExecuteAsync(
+        ExecutorBinding binding,
+        string input,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(binding);
+
+        if (binding.FactoryAsync is null)
+        {
+            throw new InvalidOperationException($"Executor binding for '{binding.Id}' does not have a factory configured.");
+        }
+
+        DurableActivityInput? inputWithState = TryDeserializeActivityInput(input);
+        string executorInput = inputWithState?.Input ?? input;
+        Dictionary<string, string> sharedState = inputWithState?.State ?? [];
+
+        Executor executor = await binding.FactoryAsync(binding.Id).ConfigureAwait(false);
+        Type inputType = ResolveInputType(inputWithState?.InputTypeName, executor.InputTypes);
+        object typedInput = DeserializeInput(executorInput, inputType);
+
+        DurableWorkflowContext workflowContext = new(sharedState, executor);
+        object? result = await executor.ExecuteCoreAsync(
+            typedInput,
+            new TypeId(inputType),
+            workflowContext,
+            WorkflowTelemetryContext.Disabled,
+            cancellationToken).ConfigureAwait(false);
+
+        return SerializeActivityOutput(result, workflowContext);
+    }
+
+    private static string SerializeActivityOutput(object? result, DurableWorkflowContext context)
+    {
+        DurableExecutorOutput output = new()
+        {
+            Result = SerializeResult(result),
+            StateUpdates = context.StateUpdates,
+            ClearedScopes = [.. context.ClearedScopes],
+            Events = context.OutboundEvents.ConvertAll(SerializeEvent),
+            SentMessages = context.SentMessages,
+            HaltRequested = context.HaltRequested
+        };
+
+        return JsonSerializer.Serialize(output, DurableWorkflowJsonContext.Default.DurableExecutorOutput);
+    }
+
+    /// <summary>
+    /// Serializes a workflow event with type information for proper deserialization.
+    /// </summary>
+    private static string SerializeEvent(WorkflowEvent evt)
+    {
+        Type eventType = evt.GetType();
+        TypedPayload wrapper = new()
+        {
+            TypeName = eventType.AssemblyQualifiedName,
+            Data = JsonSerializer.Serialize(evt, eventType, DurableSerialization.Options)
+        };
+
+        return JsonSerializer.Serialize(wrapper, DurableWorkflowJsonContext.Default.TypedPayload);
+    }
+
+    private static string SerializeResult(object? result)
+    {
+        if (result is null)
+        {
+            return string.Empty;
+        }
+
+        if (result is string str)
+        {
+            return str;
+        }
+
+        return JsonSerializer.Serialize(result, result.GetType(), DurableSerialization.Options);
+    }
+
+    private static DurableActivityInput? TryDeserializeActivityInput(string input)
+    {
+        try
+        {
+            return JsonSerializer.Deserialize(input, DurableWorkflowJsonContext.Default.DurableActivityInput);
+        }
+        catch (JsonException)
+        {
+            return null;
+        }
+    }
+
+    internal static object DeserializeInput(string input, Type targetType)
+    {
+        if (targetType == typeof(string))
+        {
+            return input;
+        }
+
+        // Fan-in aggregation serializes results as a JSON array of strings (e.g., ["{...}", "{...}"]).
+        // When the target type is a non-string array, deserialize each element individually.
+        if (targetType.IsArray && targetType != typeof(string[]))
+        {
+            Type elementType = targetType.GetElementType()!;
+            string[]? stringArray = JsonSerializer.Deserialize<string[]>(input, DurableSerialization.Options);
+            if (stringArray is not null)
+            {
+                Array result = Array.CreateInstance(elementType, stringArray.Length);
+                for (int i = 0; i < stringArray.Length; i++)
+                {
+                    object element = JsonSerializer.Deserialize(stringArray[i], elementType, DurableSerialization.Options)
+                        ?? throw new InvalidOperationException($"Failed to deserialize element {i} to type '{elementType.Name}'.");
+                    result.SetValue(element, i);
+                }
+
+                return result;
+            }
+        }
+
+        return JsonSerializer.Deserialize(input, targetType, DurableSerialization.Options)
+            ?? throw new InvalidOperationException($"Failed to deserialize input to type '{targetType.Name}'.");
+    }
+
+    internal static Type ResolveInputType(string? inputTypeName, ISet<Type> supportedTypes)
+    {
+        if (string.IsNullOrEmpty(inputTypeName))
+        {
+            return supportedTypes.FirstOrDefault() ?? typeof(string);
+        }
+
+        Type? loadedType = DurableTaskTypeResolver.Resolve(inputTypeName);
+        if (loadedType is not null && supportedTypes.Contains(loadedType))
+        {
+            return loadedType;
+        }
+
+        Type? matchedType = supportedTypes.FirstOrDefault(t =>
+            t.FullName == inputTypeName ||
+            t.Name == inputTypeName);
+
+        if (matchedType is not null)
+        {
+            return matchedType;
+        }
+
+        // Fall back if type is string or string[] but executor doesn't support it
+        if (loadedType is not null && !supportedTypes.Contains(loadedType))
+        {
+            if (loadedType == typeof(string) || loadedType == typeof(string[]))
+            {
+                return supportedTypes.FirstOrDefault() ?? typeof(string);
+            }
+        }
+
+        return loadedType ?? supportedTypes.FirstOrDefault() ?? typeof(string);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableActivityInput.cs

@@ -0,0 +1,24 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Input payload for activity execution, containing the input and other metadata.
+/// </summary>
+internal sealed class DurableActivityInput
+{
+    /// <summary>
+    /// Gets or sets the serialized executor input.
+    /// </summary>
+    public string? Input { get; set; }
+
+    /// <summary>
+    /// Gets or sets the assembly-qualified type name of the input, used for proper deserialization.
+    /// </summary>
+    public string? InputTypeName { get; set; }
+
+    /// <summary>
+    /// Gets or sets the shared state dictionary (scope-prefixed key -> serialized value).
+    /// </summary>
+    public Dictionary<string, string> State { get; set; } = [];
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableExecutorDispatcher.cs

@@ -0,0 +1,216 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// ConfigureAwait Usage in Orchestration Code:
+// This file uses ConfigureAwait(true) because it runs within orchestration context.
+// Durable Task orchestrations require deterministic replay - the same code must execute
+// identically across replays. ConfigureAwait(true) ensures continuations run on the
+// orchestration's synchronization context, which is essential for replay correctness.
+// Using ConfigureAwait(false) here could cause non-deterministic behavior during replay.
+
+using System.Text.Json;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask;
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Dispatches workflow executors to activities, AI agents, sub-orchestrations, or external events (human-in-the-loop).
+/// </summary>
+/// <remarks>
+/// Called during the dispatch phase of each superstep by
+/// <c>DurableWorkflowRunner.DispatchExecutorsInParallelAsync</c>. For each executor that has
+/// pending input, this dispatcher determines whether the executor is an AI agent (stateful,
+/// backed by Durable Entities), a request port (human-in-the-loop, backed by external events),
+/// a sub-workflow (dispatched as a sub-orchestration), or a regular activity, and invokes the
+/// appropriate Durable Task API.
+/// The serialised string result is returned to the runner for the routing phase.
+/// </remarks>
+internal static class DurableExecutorDispatcher
+{
+    /// <summary>
+    /// Dispatches an executor based on its type (activity, AI agent, request port, or sub-workflow).
+    /// </summary>
+    /// <param name="context">The task orchestration context.</param>
+    /// <param name="executorInfo">Information about the executor to dispatch.</param>
+    /// <param name="envelope">The message envelope containing input and type information.</param>
+    /// <param name="sharedState">The shared state dictionary to pass to the executor.</param>
+    /// <param name="liveStatus">The live workflow status used to publish events and pending request port state.</param>
+    /// <param name="logger">The logger for tracing.</param>
+    /// <returns>The result from the executor.</returns>
+    internal static async Task<string> DispatchAsync(
+        TaskOrchestrationContext context,
+        WorkflowExecutorInfo executorInfo,
+        DurableMessageEnvelope envelope,
+        Dictionary<string, string> sharedState,
+        DurableWorkflowLiveStatus liveStatus,
+        ILogger logger)
+    {
+        logger.LogDispatchingExecutor(executorInfo.ExecutorId, executorInfo.IsAgenticExecutor);
+
+        if (executorInfo.IsRequestPortExecutor)
+        {
+            return await ExecuteRequestPortAsync(context, executorInfo, envelope.Message, liveStatus, logger).ConfigureAwait(true);
+        }
+
+        if (executorInfo.IsAgenticExecutor)
+        {
+            return await ExecuteAgentAsync(context, executorInfo, logger, envelope.Message).ConfigureAwait(true);
+        }
+
+        if (executorInfo.IsSubworkflowExecutor)
+        {
+            return await ExecuteSubWorkflowAsync(context, executorInfo, envelope.Message).ConfigureAwait(true);
+        }
+
+        return await ExecuteActivityAsync(context, executorInfo, envelope.Message, envelope.InputTypeName, sharedState).ConfigureAwait(true);
+    }
+
+    private static async Task<string> ExecuteActivityAsync(
+        TaskOrchestrationContext context,
+        WorkflowExecutorInfo executorInfo,
+        string input,
+        string? inputTypeName,
+        Dictionary<string, string> sharedState)
+    {
+        string executorName = WorkflowNamingHelper.GetExecutorName(executorInfo.ExecutorId);
+        string activityName = WorkflowNamingHelper.ToOrchestrationFunctionName(executorName);
+
+        DurableActivityInput activityInput = new()
+        {
+            Input = input,
+            InputTypeName = inputTypeName,
+            State = sharedState
+        };
+
+        string serializedInput = JsonSerializer.Serialize(activityInput, DurableWorkflowJsonContext.Default.DurableActivityInput);
+
+        return await context.CallActivityAsync<string>(activityName, serializedInput).ConfigureAwait(true);
+    }
+
+    /// <summary>
+    /// Executes a request port executor by waiting for an external event (human-in-the-loop).
+    /// </summary>
+    /// <remarks>
+    /// When the workflow reaches a <see cref="RequestPort"/> executor, the orchestration publishes
+    /// the pending request to <see cref="DurableWorkflowLiveStatus"/> and waits for an external actor
+    /// (e.g., a UI or API) to raise the corresponding event via
+    /// <see cref="IStreamingWorkflowRun.SendResponseAsync{TResponse}(DurableWorkflowWaitingForInputEvent, TResponse, CancellationToken)"/>.
+    /// Multiple RequestPorts may be dispatched in parallel during a fan-out superstep.
+    /// Each adds its pending request to <see cref="DurableWorkflowLiveStatus.PendingEvents"/>.
+    /// The wait has no built-in timeout; for time-limited approvals, callers can combine
+    /// <c>context.CreateTimer</c> with <c>Task.WhenAny</c> in a wrapper executor.
+    /// </remarks>
+    private static async Task<string> ExecuteRequestPortAsync(
+        TaskOrchestrationContext context,
+        WorkflowExecutorInfo executorInfo,
+        string input,
+        DurableWorkflowLiveStatus liveStatus,
+        ILogger logger)
+    {
+        RequestPort requestPort = executorInfo.RequestPort!;
+        string eventName = requestPort.Id;
+
+        logger.LogWaitingForExternalEvent(eventName);
+
+        // Publish pending request so external clients can discover what input is needed
+        liveStatus.PendingEvents.Add(new PendingRequestPortStatus(EventName: eventName, Input: input));
+        context.SetCustomStatus(liveStatus);
+
+        // Wait until the external actor raises the event
+        string response = await context.WaitForExternalEvent<string>(eventName).ConfigureAwait(true);
+
+        // Remove this pending request after receiving the response
+        liveStatus.PendingEvents.RemoveAll(p => p.EventName == eventName);
+        context.SetCustomStatus(liveStatus.Events.Count > 0 || liveStatus.PendingEvents.Count > 0 ? liveStatus : null);
+
+        logger.LogReceivedExternalEvent(eventName);
+
+        return response;
+    }
+
+    /// <summary>
+    /// Executes an AI agent executor through Durable Entities.
+    /// </summary>
+    /// <remarks>
+    /// AI agents are stateful and maintain conversation history. They use Durable Entities
+    /// to persist state across orchestration replays.
+    /// </remarks>
+    private static async Task<string> ExecuteAgentAsync(
+        TaskOrchestrationContext context,
+        WorkflowExecutorInfo executorInfo,
+        ILogger logger,
+        string input)
+    {
+        string agentName = WorkflowNamingHelper.GetExecutorName(executorInfo.ExecutorId);
+        DurableAIAgent agent = context.GetAgent(agentName);
+
+        if (agent is null)
+        {
+            logger.LogAgentNotFound(agentName);
+            return $"Agent '{agentName}' not found";
+        }
+
+        AgentSession session = await agent.CreateSessionAsync().ConfigureAwait(true);
+        AgentResponse response = await agent.RunAsync(input, session).ConfigureAwait(true);
+
+        return response.Text;
+    }
+
+    /// <summary>
+    /// Dispatches a sub-workflow executor as a sub-orchestration.
+    /// </summary>
+    /// <remarks>
+    /// Sub-workflows run as separate orchestration instances, providing independent
+    /// checkpointing, replay, and hierarchical visualization in the DTS dashboard.
+    /// The input is wrapped in <see cref="DurableWorkflowInput{T}"/> so the sub-orchestration
+    /// can extract it using the same envelope structure. The sub-orchestration returns a
+    /// <see cref="DurableWorkflowResult"/> directly (deserialized by the Durable Task SDK),
+    /// which this method converts to a <see cref="DurableExecutorOutput"/> so the parent
+    /// workflow's result processing picks up both the result and any accumulated events.
+    /// </remarks>
+    private static async Task<string> ExecuteSubWorkflowAsync(
+        TaskOrchestrationContext context,
+        WorkflowExecutorInfo executorInfo,
+        string input)
+    {
+        string orchestrationName = WorkflowNamingHelper.ToOrchestrationFunctionName(executorInfo.SubWorkflow!.Name!);
+
+        DurableWorkflowInput<string> workflowInput = new() { Input = input };
+
+        DurableWorkflowResult? workflowResult = await context.CallSubOrchestratorAsync<DurableWorkflowResult?>(
+            orchestrationName,
+            workflowInput).ConfigureAwait(true);
+
+        return ConvertWorkflowResultToExecutorOutput(workflowResult);
+    }
+
+    /// <summary>
+    /// Converts a <see cref="DurableWorkflowResult"/> from a sub-orchestration
+    /// into a <see cref="DurableExecutorOutput"/> JSON string. This bridges the sub-workflow's
+    /// output format to the parent workflow's result processing, preserving both the result
+    /// and any accumulated events from the sub-workflow.
+    /// </summary>
+    private static string ConvertWorkflowResultToExecutorOutput(DurableWorkflowResult? workflowResult)
+    {
+        if (workflowResult is null)
+        {
+            return string.Empty;
+        }
+
+        // Propagate the result, events, and sent messages from the sub-workflow.
+        // SentMessages carry the sub-workflow's output for typed routing in the parent,
+        // matching the in-process WorkflowHostExecutor behavior.
+        // Shared state is not included because each workflow instance maintains its own
+        // independent shared state; it is not shared between parent and sub-workflows.
+        DurableExecutorOutput executorOutput = new()
+        {
+            Result = workflowResult.Result,
+            Events = workflowResult.Events ?? [],
+            SentMessages = workflowResult.SentMessages ?? [],
+            HaltRequested = workflowResult.HaltRequested,
+        };
+
+        return JsonSerializer.Serialize(executorOutput, DurableWorkflowJsonContext.Default.DurableExecutorOutput);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableExecutorOutput.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Output payload from executor execution, containing the result, state updates, and emitted events.
+/// </summary>
+internal sealed class DurableExecutorOutput
+{
+    /// <summary>
+    /// Gets the executor result.
+    /// </summary>
+    public string? Result { get; init; }
+
+    /// <summary>
+    /// Gets the state updates (scope-prefixed key to value; null indicates deletion).
+    /// </summary>
+    public Dictionary<string, string?> StateUpdates { get; init; } = [];
+
+    /// <summary>
+    /// Gets the scope names that were cleared.
+    /// </summary>
+    public List<string> ClearedScopes { get; init; } = [];
+
+    /// <summary>
+    /// Gets the workflow events emitted during execution.
+    /// </summary>
+    public List<string> Events { get; init; } = [];
+
+    /// <summary>
+    /// Gets the typed messages sent to downstream executors.
+    /// </summary>
+    public List<TypedPayload> SentMessages { get; init; } = [];
+
+    /// <summary>
+    /// Gets a value indicating whether the executor requested a workflow halt.
+    /// </summary>
+    public bool HaltRequested { get; init; }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableHaltRequestedEvent.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Event raised when an executor requests the workflow to halt via <see cref="IWorkflowContext.RequestHaltAsync"/>.
+/// </summary>
+public sealed class DurableHaltRequestedEvent : WorkflowEvent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableHaltRequestedEvent"/> class.
+    /// </summary>
+    /// <param name="executorId">The ID of the executor that requested the halt.</param>
+    public DurableHaltRequestedEvent(string executorId) : base($"Halt requested by {executorId}")
+    {
+        this.ExecutorId = executorId;
+    }
+
+    /// <summary>
+    /// Gets the ID of the executor that requested the halt.
+    /// </summary>
+    public string ExecutorId { get; }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableMessageEnvelope.cs

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Represents a message envelope for durable workflow message passing.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This is the durable equivalent of <c>MessageEnvelope</c> in the in-process runner.
+/// Unlike the in-process version which holds native .NET objects, this envelope
+/// contains serialized JSON strings suitable for Durable Task activities.
+/// </para>
+/// </remarks>
+internal sealed class DurableMessageEnvelope
+{
+    /// <summary>
+    /// Gets or sets the serialized JSON message content.
+    /// </summary>
+    public required string Message { get; init; }
+
+    /// <summary>
+    /// Gets or sets the full type name of the message for deserialization.
+    /// </summary>
+    public string? InputTypeName { get; init; }
+
+    /// <summary>
+    /// Gets or sets the ID of the executor that produced this message.
+    /// </summary>
+    /// <remarks>
+    /// Used for tracing and debugging. Null for initial workflow input.
+    /// </remarks>
+    public string? SourceExecutorId { get; init; }
+
+    /// <summary>
+    /// Creates a new message envelope.
+    /// </summary>
+    /// <param name="message">The serialized JSON message content.</param>
+    /// <param name="inputTypeName">The full type name of the message for deserialization.</param>
+    /// <param name="sourceExecutorId">The ID of the executor that produced this message, or null for initial input.</param>
+    /// <returns>A new <see cref="DurableMessageEnvelope"/> instance.</returns>
+    internal static DurableMessageEnvelope Create(string message, string? inputTypeName, string? sourceExecutorId = null)
+    {
+        return new DurableMessageEnvelope
+        {
+            Message = message,
+            InputTypeName = inputTypeName,
+            SourceExecutorId = sourceExecutorId
+        };
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableRunStatus.cs

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Represents the execution status of a durable workflow run.
+/// </summary>
+public enum DurableRunStatus
+{
+    /// <summary>
+    /// The workflow instance was not found.
+    /// </summary>
+    NotFound,
+
+    /// <summary>
+    /// The workflow is pending and has not started.
+    /// </summary>
+    Pending,
+
+    /// <summary>
+    /// The workflow is currently running.
+    /// </summary>
+    Running,
+
+    /// <summary>
+    /// The workflow completed successfully.
+    /// </summary>
+    Completed,
+
+    /// <summary>
+    /// The workflow failed with an error.
+    /// </summary>
+    Failed,
+
+    /// <summary>
+    /// The workflow was terminated.
+    /// </summary>
+    Terminated,
+
+    /// <summary>
+    /// The workflow is suspended.
+    /// </summary>
+    Suspended,
+
+    /// <summary>
+    /// The workflow status is unknown.
+    /// </summary>
+    Unknown
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableSerialization.cs

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Shared serialization options for user-defined workflow types that are not known at compile time
+/// and therefore cannot use the source-generated <see cref="DurableWorkflowJsonContext"/>.
+/// </summary>
+internal static class DurableSerialization
+{
+    /// <summary>
+    /// Gets the shared <see cref="JsonSerializerOptions"/> for workflow serialization
+    /// with camelCase naming and case-insensitive deserialization.
+    /// </summary>
+    internal static JsonSerializerOptions Options { get; } = new()
+    {
+        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
+        PropertyNameCaseInsensitive = true
+    };
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableStreamingWorkflowRun.cs

@@ -0,0 +1,452 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask;
+using Microsoft.DurableTask.Client;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Represents a durable workflow run that supports streaming workflow events as they occur.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Events are detected by monitoring the orchestration's custom status at regular intervals.
+/// When executors emit events via <see cref="IWorkflowContext.AddEventAsync"/> or
+/// <see cref="IWorkflowContext.YieldOutputAsync"/>, they are written to the orchestration's
+/// custom status and picked up by this streaming run.
+/// </para>
+/// <para>
+/// When the workflow reaches a <see cref="RequestPort"/> executor, a <see cref="DurableWorkflowWaitingForInputEvent"/>
+/// is yielded containing the request data. The caller should then call
+/// <see cref="SendResponseAsync{TResponse}(DurableWorkflowWaitingForInputEvent, TResponse, CancellationToken)"/>
+/// to provide the response and resume the workflow.
+/// </para>
+/// </remarks>
+[DebuggerDisplay("{WorkflowName} ({RunId})")]
+internal sealed class DurableStreamingWorkflowRun : IStreamingWorkflowRun
+{
+    private readonly DurableTaskClient _client;
+    private readonly Dictionary<string, RequestPort> _requestPorts;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableStreamingWorkflowRun"/> class.
+    /// </summary>
+    /// <param name="client">The durable task client for orchestration operations.</param>
+    /// <param name="instanceId">The unique instance ID for this orchestration run.</param>
+    /// <param name="workflow">The workflow being executed.</param>
+    internal DurableStreamingWorkflowRun(DurableTaskClient client, string instanceId, Workflow workflow)
+    {
+        this._client = client;
+        this.RunId = instanceId;
+        this.WorkflowName = workflow.Name ?? string.Empty;
+        this._requestPorts = ExtractRequestPorts(workflow);
+    }
+
+    /// <inheritdoc/>
+    public string RunId { get; }
+
+    /// <summary>
+    /// Gets the name of the workflow being executed.
+    /// </summary>
+    public string WorkflowName { get; }
+
+    /// <summary>
+    /// Gets the current execution status of the workflow run.
+    /// </summary>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>The current status of the durable run.</returns>
+    public async ValueTask<DurableRunStatus> GetStatusAsync(CancellationToken cancellationToken = default)
+    {
+        OrchestrationMetadata? metadata = await this._client.GetInstanceAsync(
+            this.RunId,
+            getInputsAndOutputs: false,
+            cancellation: cancellationToken).ConfigureAwait(false);
+
+        if (metadata is null)
+        {
+            return DurableRunStatus.NotFound;
+        }
+
+        return metadata.RuntimeStatus switch
+        {
+            OrchestrationRuntimeStatus.Pending => DurableRunStatus.Pending,
+            OrchestrationRuntimeStatus.Running => DurableRunStatus.Running,
+            OrchestrationRuntimeStatus.Completed => DurableRunStatus.Completed,
+            OrchestrationRuntimeStatus.Failed => DurableRunStatus.Failed,
+            OrchestrationRuntimeStatus.Terminated => DurableRunStatus.Terminated,
+            OrchestrationRuntimeStatus.Suspended => DurableRunStatus.Suspended,
+            _ => DurableRunStatus.Unknown
+        };
+    }
+
+    /// <inheritdoc/>
+    public IAsyncEnumerable<WorkflowEvent> WatchStreamAsync(CancellationToken cancellationToken = default)
+        => this.WatchStreamAsync(pollingInterval: null, cancellationToken);
+
+    /// <summary>
+    /// Asynchronously streams workflow events as they occur during workflow execution.
+    /// </summary>
+    /// <param name="pollingInterval">The interval between status checks. Defaults to 100ms.</param>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>An asynchronous stream of <see cref="WorkflowEvent"/> objects.</returns>
+    private async IAsyncEnumerable<WorkflowEvent> WatchStreamAsync(
+        TimeSpan? pollingInterval,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        TimeSpan minInterval = pollingInterval ?? TimeSpan.FromMilliseconds(100);
+        TimeSpan maxInterval = TimeSpan.FromSeconds(2);
+        TimeSpan currentInterval = minInterval;
+
+        // Track how many events we've already read from the durable workflow status
+        int lastReadEventIndex = 0;
+
+        // Track which pending events we've already yielded to avoid duplicates
+        HashSet<string> yieldedPendingEvents = [];
+
+        while (!cancellationToken.IsCancellationRequested)
+        {
+            // Poll with getInputsAndOutputs: true because SerializedCustomStatus
+            // (used for event streaming) is only populated when this flag is set.
+            OrchestrationMetadata? metadata = await this._client.GetInstanceAsync(
+                this.RunId,
+                getInputsAndOutputs: true,
+                cancellation: cancellationToken).ConfigureAwait(false);
+
+            if (metadata is null)
+            {
+                yield break;
+            }
+
+            bool hasNewEvents = false;
+
+            // Always drain any unread events from the durable workflow status before checking terminal states.
+            // The orchestration may complete before the next poll, so events would be lost if we
+            // check terminal status first.
+            if (metadata.SerializedCustomStatus is not null)
+            {
+                if (DurableWorkflowLiveStatus.TryParse(metadata.SerializedCustomStatus, out DurableWorkflowLiveStatus liveStatus))
+                {
+                    (List<WorkflowEvent> events, lastReadEventIndex) = DrainNewEvents(liveStatus.Events, lastReadEventIndex);
+                    foreach (WorkflowEvent evt in events)
+                    {
+                        hasNewEvents = true;
+                        yield return evt;
+                    }
+
+                    // Yield a DurableWorkflowWaitingForInputEvent for each new pending request port
+                    foreach (PendingRequestPortStatus pending in liveStatus.PendingEvents)
+                    {
+                        if (yieldedPendingEvents.Add(pending.EventName))
+                        {
+                            if (!this._requestPorts.TryGetValue(pending.EventName, out RequestPort? matchingPort))
+                            {
+                                // RequestPort may not exist in the current workflow definition (e.g., during rolling deployments).
+                                continue;
+                            }
+
+                            hasNewEvents = true;
+                            yield return new DurableWorkflowWaitingForInputEvent(
+                                pending.Input,
+                                matchingPort);
+                        }
+                    }
+
+                    // Sync tracking with current pending events so re-used RequestPort names can be yielded again
+                    if (liveStatus.PendingEvents.Count == 0)
+                    {
+                        yieldedPendingEvents.Clear();
+                    }
+                    else
+                    {
+                        yieldedPendingEvents.IntersectWith(liveStatus.PendingEvents.Select(p => p.EventName));
+                    }
+                }
+            }
+
+            // Check terminal states after draining events from the durable workflow status
+            if (metadata.RuntimeStatus == OrchestrationRuntimeStatus.Completed)
+            {
+                // The framework clears the durable workflow status on completion, so events may be in
+                // SerializedOutput as a DurableWorkflowResult wrapper.
+                if (TryParseWorkflowResult(metadata.SerializedOutput, out DurableWorkflowResult? outputResult))
+                {
+                    (List<WorkflowEvent> events, _) = DrainNewEvents(outputResult.Events, lastReadEventIndex);
+                    foreach (WorkflowEvent evt in events)
+                    {
+                        yield return evt;
+                    }
+
+                    yield return new DurableWorkflowCompletedEvent(outputResult.Result);
+                }
+                else
+                {
+                    // The runner always wraps output in DurableWorkflowResult, so a parse
+                    // failure here indicates a bug. Yield a failed event so the consumer
+                    // gets a visible, handleable signal without crashing.
+                    yield return new DurableWorkflowFailedEvent(
+                        $"Workflow '{this.WorkflowName}' (RunId: {this.RunId}) completed but its output could not be parsed as DurableWorkflowResult.");
+                }
+
+                yield break;
+            }
+
+            if (metadata.RuntimeStatus == OrchestrationRuntimeStatus.Failed)
+            {
+                string errorMessage = metadata.FailureDetails?.ErrorMessage ?? "Workflow execution failed.";
+                yield return new DurableWorkflowFailedEvent(errorMessage, metadata.FailureDetails);
+                yield break;
+            }
+
+            if (metadata.RuntimeStatus == OrchestrationRuntimeStatus.Terminated)
+            {
+                yield return new DurableWorkflowFailedEvent("Workflow was terminated.");
+                yield break;
+            }
+
+            // Adaptive backoff: reset to minimum when events were found, increase otherwise
+            currentInterval = hasNewEvents
+                ? minInterval
+                : TimeSpan.FromMilliseconds(Math.Min(currentInterval.TotalMilliseconds * 2, maxInterval.TotalMilliseconds));
+
+            try
+            {
+                await Task.Delay(currentInterval, cancellationToken).ConfigureAwait(false);
+            }
+            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
+            {
+                yield break;
+            }
+        }
+    }
+
+    /// <summary>
+    /// Sends a response to a <see cref="DurableWorkflowWaitingForInputEvent"/> to resume the workflow.
+    /// </summary>
+    /// <typeparam name="TResponse">The type of the response data.</typeparam>
+    /// <param name="requestEvent">The request event to respond to.</param>
+    /// <param name="response">The response data to send.</param>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Serializing workflow types provided by the caller.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Serializing workflow types provided by the caller.")]
+    public async ValueTask SendResponseAsync<TResponse>(DurableWorkflowWaitingForInputEvent requestEvent, TResponse response, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(requestEvent);
+
+        string serializedResponse = JsonSerializer.Serialize(response, DurableSerialization.Options);
+        await this._client.RaiseEventAsync(
+            this.RunId,
+            requestEvent.RequestPort.Id,
+            serializedResponse,
+            cancellationToken).ConfigureAwait(false);
+    }
+
+    /// <summary>
+    /// Waits for the workflow to complete and returns the result.
+    /// </summary>
+    /// <typeparam name="TResult">The expected result type.</typeparam>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>The result of the workflow execution.</returns>
+    /// <exception cref="TaskFailedException">Thrown when the workflow failed.</exception>
+    /// <exception cref="InvalidOperationException">Thrown when the workflow was terminated or ended with an unexpected status.</exception>
+    public async ValueTask<TResult?> WaitForCompletionAsync<TResult>(CancellationToken cancellationToken = default)
+    {
+        OrchestrationMetadata metadata = await this._client.WaitForInstanceCompletionAsync(
+            this.RunId,
+            getInputsAndOutputs: true,
+            cancellation: cancellationToken).ConfigureAwait(false);
+
+        if (metadata.RuntimeStatus == OrchestrationRuntimeStatus.Completed)
+        {
+            return ExtractResult<TResult>(metadata.SerializedOutput);
+        }
+
+        if (metadata.RuntimeStatus == OrchestrationRuntimeStatus.Failed)
+        {
+            if (metadata.FailureDetails is not null)
+            {
+                throw new TaskFailedException(
+                    taskName: this.WorkflowName,
+                    taskId: -1,
+                    failureDetails: metadata.FailureDetails);
+            }
+
+            throw new InvalidOperationException(
+                $"Workflow '{this.WorkflowName}' (RunId: {this.RunId}) failed without failure details.");
+        }
+
+        throw new InvalidOperationException(
+            $"Workflow '{this.WorkflowName}' (RunId: {this.RunId}) ended with unexpected status: {metadata.RuntimeStatus}");
+    }
+
+    /// <summary>
+    /// Deserializes and returns any events beyond <paramref name="lastReadIndex"/> from the list.
+    /// </summary>
+    private static (List<WorkflowEvent> Events, int UpdatedIndex) DrainNewEvents(List<string> serializedEvents, int lastReadIndex)
+    {
+        List<WorkflowEvent> events = [];
+        while (lastReadIndex < serializedEvents.Count)
+        {
+            string serializedEvent = serializedEvents[lastReadIndex];
+            lastReadIndex++;
+
+            WorkflowEvent? workflowEvent = TryDeserializeEvent(serializedEvent);
+            if (workflowEvent is not null)
+            {
+                events.Add(workflowEvent);
+            }
+        }
+
+        return (events, lastReadIndex);
+    }
+
+    /// <summary>
+    /// Attempts to parse the orchestration output as a <see cref="DurableWorkflowResult"/> wrapper.
+    /// </summary>
+    /// <remarks>
+    /// The orchestration returns a <see cref="DurableWorkflowResult"/> object directly.
+    /// The Durable Task framework's <c>DataConverter</c> serializes it as a JSON object
+    /// in <c>SerializedOutput</c>, so we deserialize it directly.
+    /// </remarks>
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing workflow result wrapper.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing workflow result wrapper.")]
+    private static bool TryParseWorkflowResult(string? serializedOutput, [NotNullWhen(true)] out DurableWorkflowResult? result)
+    {
+        if (serializedOutput is null)
+        {
+            result = default!;
+            return false;
+        }
+
+        try
+        {
+            result = JsonSerializer.Deserialize(serializedOutput, DurableWorkflowJsonContext.Default.DurableWorkflowResult)!;
+            return result is not null;
+        }
+        catch (JsonException)
+        {
+            result = default!;
+            return false;
+        }
+    }
+
+    /// <summary>
+    /// Extracts a typed result from the orchestration output by unwrapping the
+    /// <see cref="DurableWorkflowResult"/> wrapper.
+    /// </summary>
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing workflow result.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing workflow result.")]
+    internal static TResult? ExtractResult<TResult>(string? serializedOutput)
+    {
+        if (serializedOutput is null)
+        {
+            return default;
+        }
+
+        if (!TryParseWorkflowResult(serializedOutput, out DurableWorkflowResult? workflowResult))
+        {
+            throw new InvalidOperationException(
+                "Failed to parse orchestration output as DurableWorkflowResult. " +
+                "The orchestration runner should always wrap output in this format.");
+        }
+
+        string? resultJson = workflowResult.Result;
+
+        if (resultJson is null)
+        {
+            return default;
+        }
+
+        if (typeof(TResult) == typeof(string))
+        {
+            return (TResult)(object)resultJson;
+        }
+
+        return JsonSerializer.Deserialize<TResult>(resultJson, DurableSerialization.Options);
+    }
+
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing workflow event types.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing workflow event types.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2057", Justification = "Event types are registered at startup.")]
+    private static WorkflowEvent? TryDeserializeEvent(string serializedEvent)
+    {
+        try
+        {
+            TypedPayload? wrapper = JsonSerializer.Deserialize(
+                serializedEvent,
+                DurableWorkflowJsonContext.Default.TypedPayload);
+
+            if (wrapper?.TypeName is not null && wrapper.Data is not null)
+            {
+                Type? eventType = DurableTaskTypeResolver.Resolve(wrapper.TypeName);
+                if (eventType is not null)
+                {
+                    return DeserializeEventByType(eventType, wrapper.Data);
+                }
+            }
+
+            return null;
+        }
+        catch (JsonException)
+        {
+            return null;
+        }
+    }
+
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing workflow event types.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing workflow event types.")]
+    private static WorkflowEvent? DeserializeEventByType(Type eventType, string json)
+    {
+        // Types with internal constructors need manual deserialization
+        if (eventType == typeof(ExecutorInvokedEvent)
+            || eventType == typeof(ExecutorCompletedEvent)
+            || eventType == typeof(WorkflowOutputEvent))
+        {
+            using JsonDocument doc = JsonDocument.Parse(json);
+            JsonElement root = doc.RootElement;
+
+            if (eventType == typeof(ExecutorInvokedEvent))
+            {
+                string executorId = root.GetProperty("executorId").GetString() ?? string.Empty;
+                JsonElement? data = GetDataProperty(root);
+                return new ExecutorInvokedEvent(executorId, data!);
+            }
+
+            if (eventType == typeof(ExecutorCompletedEvent))
+            {
+                string executorId = root.GetProperty("executorId").GetString() ?? string.Empty;
+                JsonElement? data = GetDataProperty(root);
+                return new ExecutorCompletedEvent(executorId, data);
+            }
+
+            // WorkflowOutputEvent
+            string sourceId = root.GetProperty("sourceId").GetString() ?? string.Empty;
+            object? outputData = GetDataProperty(root);
+            return new WorkflowOutputEvent(outputData!, sourceId);
+        }
+
+        return JsonSerializer.Deserialize(json, eventType, DurableSerialization.Options) as WorkflowEvent;
+    }
+
+    private static JsonElement? GetDataProperty(JsonElement root)
+    {
+        if (!root.TryGetProperty("data", out JsonElement dataElement))
+        {
+            return null;
+        }
+
+        return dataElement.ValueKind == JsonValueKind.Null ? null : dataElement.Clone();
+    }
+
+    private static Dictionary<string, RequestPort> ExtractRequestPorts(Workflow workflow)
+    {
+        return WorkflowAnalyzer.GetExecutorsFromWorkflowInOrder(workflow)
+            .Where(e => e.RequestPort is not null)
+            .ToDictionary(e => e.RequestPort!.Id, e => e.RequestPort!);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableTaskTypeResolver.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Concurrent;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Agents.AI.Workflows.Checkpointing;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Resolves persisted assembly-qualified type-name strings to a loaded <see cref="Type"/>,
+/// tolerating differences in assembly version, culture, and public key token between the
+/// persisted name and the currently loaded assemblies. Results are cached.
+/// </summary>
+internal static class DurableTaskTypeResolver
+{
+    private static readonly ConcurrentDictionary<string, Type?> s_cache = new();
+
+    /// <summary>
+    /// Resolves <paramref name="typeName"/> using a qualified <see cref="Type.GetType(string, bool)"/>
+    /// lookup, then a partial-name fallback that strips embedded version, culture, and public key
+    /// token qualifiers.
+    /// </summary>
+    [UnconditionalSuppressMessage("Trimming", "IL2026:Members annotated with 'RequiresUnreferencedCodeAttribute' require dynamic access", Justification = "Workflow message and event types are registered at startup.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2057:Unrecognized value passed to the parameter of method", Justification = "Workflow message and event types are registered at startup.")]
+    internal static Type? Resolve(string typeName)
+        => s_cache.GetOrAdd(typeName, static name =>
+        {
+            Type? type = Type.GetType(name, throwOnError: false);
+            if (type is not null)
+            {
+                return type;
+            }
+
+            string normalized = TypeId.NormalizeTypeName(name);
+            return ReferenceEquals(normalized, name)
+                ? null
+                : Type.GetType(normalized, throwOnError: false);
+        });
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowClient.cs

@@ -0,0 +1,95 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask;
+using Microsoft.DurableTask.Client;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Provides a durable task-based implementation of <see cref="IWorkflowClient"/> for running
+/// workflows as durable orchestrations.
+/// </summary>
+internal sealed class DurableWorkflowClient : IWorkflowClient
+{
+    private readonly DurableTaskClient _client;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableWorkflowClient"/> class.
+    /// </summary>
+    /// <param name="client">The durable task client for orchestration operations.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="client"/> is null.</exception>
+    public DurableWorkflowClient(DurableTaskClient client)
+    {
+        ArgumentNullException.ThrowIfNull(client);
+        this._client = client;
+    }
+
+    /// <inheritdoc/>
+    public async ValueTask<IWorkflowRun> RunAsync<TInput>(
+        Workflow workflow,
+        TInput input,
+        string? runId = null,
+        CancellationToken cancellationToken = default)
+        where TInput : notnull
+    {
+        ArgumentNullException.ThrowIfNull(workflow);
+
+        if (string.IsNullOrEmpty(workflow.Name))
+        {
+            throw new ArgumentException("Workflow must have a valid Name property.", nameof(workflow));
+        }
+
+        DurableWorkflowInput<TInput> workflowInput = new() { Input = input };
+
+        string instanceId = await this._client.ScheduleNewOrchestrationInstanceAsync(
+            orchestratorName: WorkflowNamingHelper.ToOrchestrationFunctionName(workflow.Name),
+            input: workflowInput,
+            options: runId is not null ? new StartOrchestrationOptions(runId) : null,
+            cancellation: cancellationToken).ConfigureAwait(false);
+
+        return new DurableWorkflowRun(this._client, instanceId, workflow.Name);
+    }
+
+    /// <inheritdoc/>
+    public ValueTask<IWorkflowRun> RunAsync(
+        Workflow workflow,
+        string input,
+        string? runId = null,
+        CancellationToken cancellationToken = default)
+        => this.RunAsync<string>(workflow, input, runId, cancellationToken);
+
+    /// <inheritdoc/>
+    public async ValueTask<IStreamingWorkflowRun> StreamAsync<TInput>(
+        Workflow workflow,
+        TInput input,
+        string? runId = null,
+        CancellationToken cancellationToken = default)
+        where TInput : notnull
+    {
+        ArgumentNullException.ThrowIfNull(workflow);
+
+        if (string.IsNullOrEmpty(workflow.Name))
+        {
+            throw new ArgumentException("Workflow must have a valid Name property.", nameof(workflow));
+        }
+
+        DurableWorkflowInput<TInput> workflowInput = new() { Input = input };
+
+        string instanceId = await this._client.ScheduleNewOrchestrationInstanceAsync(
+            orchestratorName: WorkflowNamingHelper.ToOrchestrationFunctionName(workflow.Name),
+            input: workflowInput,
+            options: runId is not null ? new StartOrchestrationOptions(runId) : null,
+            cancellation: cancellationToken).ConfigureAwait(false);
+
+        return new DurableStreamingWorkflowRun(this._client, instanceId, workflow);
+    }
+
+    /// <inheritdoc/>
+    public ValueTask<IStreamingWorkflowRun> StreamAsync(
+        Workflow workflow,
+        string input,
+        string? runId = null,
+        CancellationToken cancellationToken = default)
+        => this.StreamAsync<string>(workflow, input, runId, cancellationToken);
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowCompletedEvent.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Event raised when a durable workflow completes successfully.
+/// </summary>
+[DebuggerDisplay("Completed: {Result}")]
+public sealed class DurableWorkflowCompletedEvent : WorkflowEvent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableWorkflowCompletedEvent"/> class.
+    /// </summary>
+    /// <param name="result">The serialized result of the workflow.</param>
+    public DurableWorkflowCompletedEvent(string? result) : base(result)
+    {
+        this.Result = result;
+    }
+
+    /// <summary>
+    /// Gets the serialized result of the workflow.
+    /// </summary>
+    public string? Result { get; }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowContext.cs

@@ -0,0 +1,327 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// A workflow context for durable workflow execution.
+/// </summary>
+/// <remarks>
+/// State is passed in from the orchestration and updates are collected for return.
+/// Events emitted during execution are collected and returned to the orchestration
+/// as part of the activity output for streaming to callers.
+/// </remarks>
+[DebuggerDisplay("Executor = {_executor.Id}, StateEntries = {_initialState.Count}")]
+internal sealed class DurableWorkflowContext : IWorkflowContext
+{
+    /// <summary>
+    /// The default scope name used when no explicit scope is specified.
+    /// Scopes partition shared state into logical namespaces so that different
+    /// parts of a workflow can manage their state keys independently.
+    /// </summary>
+    private const string DefaultScopeName = "__default__";
+
+    private readonly Dictionary<string, string> _initialState;
+    private readonly Executor _executor;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableWorkflowContext"/> class.
+    /// </summary>
+    /// <param name="initialState">The shared state passed from the orchestration.</param>
+    /// <param name="executor">The executor running in this context.</param>
+    internal DurableWorkflowContext(Dictionary<string, string>? initialState, Executor executor)
+    {
+        this._executor = executor;
+        this._initialState = initialState ?? [];
+    }
+
+    /// <summary>
+    /// Gets the messages sent during activity execution via <see cref="SendMessageAsync"/>.
+    /// </summary>
+    internal List<TypedPayload> SentMessages { get; } = [];
+
+    /// <summary>
+    /// Gets the outbound events that were added during activity execution.
+    /// </summary>
+    internal List<WorkflowEvent> OutboundEvents { get; } = [];
+
+    /// <summary>
+    /// Gets the state updates made during activity execution.
+    /// </summary>
+    internal Dictionary<string, string?> StateUpdates { get; } = [];
+
+    /// <summary>
+    /// Gets the scopes that were cleared during activity execution.
+    /// </summary>
+    internal HashSet<string> ClearedScopes { get; } = [];
+
+    /// <summary>
+    /// Gets a value indicating whether the executor requested a workflow halt.
+    /// </summary>
+    internal bool HaltRequested { get; private set; }
+
+    /// <inheritdoc/>
+    public ValueTask AddEventAsync(
+        WorkflowEvent workflowEvent,
+        CancellationToken cancellationToken = default)
+    {
+        if (workflowEvent is not null)
+        {
+            this.OutboundEvents.Add(workflowEvent);
+        }
+
+        return default;
+    }
+
+    /// <inheritdoc/>
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Serializing workflow message types registered at startup.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Serializing workflow message types registered at startup.")]
+    public ValueTask SendMessageAsync(
+        object message,
+        string? targetId = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (message is not null)
+        {
+            Type messageType = message.GetType();
+            this.SentMessages.Add(new TypedPayload
+            {
+                Data = JsonSerializer.Serialize(message, messageType, DurableSerialization.Options),
+                TypeName = messageType.AssemblyQualifiedName
+            });
+        }
+
+        return default;
+    }
+
+    /// <inheritdoc/>
+    public ValueTask YieldOutputAsync(
+        object output,
+        CancellationToken cancellationToken = default)
+    {
+        if (output is not null)
+        {
+            Type outputType = output.GetType();
+            if (!this._executor.CanOutput(outputType))
+            {
+                throw new InvalidOperationException(
+                    $"Cannot output object of type {outputType.Name}. " +
+                    $"Expecting one of [{string.Join(", ", this._executor.OutputTypes)}].");
+            }
+
+            this.OutboundEvents.Add(new WorkflowOutputEvent(output, this._executor.Id));
+        }
+
+        return default;
+    }
+
+    /// <inheritdoc/>
+    public ValueTask RequestHaltAsync()
+    {
+        this.HaltRequested = true;
+        this.OutboundEvents.Add(new DurableHaltRequestedEvent(this._executor.Id));
+        return default;
+    }
+
+    /// <inheritdoc/>
+    public ValueTask<T?> ReadStateAsync<T>(
+        string key,
+        string? scopeName = null,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(key);
+
+        string scopeKey = GetScopeKey(scopeName, key);
+        string normalizedScope = scopeName ?? DefaultScopeName;
+        bool scopeCleared = this.ClearedScopes.Contains(normalizedScope);
+
+        // Local updates take priority over initial state.
+        if (this.StateUpdates.TryGetValue(scopeKey, out string? updated))
+        {
+            return DeserializeStateAsync<T>(updated);
+        }
+
+        // If scope was cleared, ignore initial state
+        if (scopeCleared)
+        {
+            return ValueTask.FromResult<T?>(default);
+        }
+
+        // Fall back to initial state passed from orchestration
+        if (this._initialState.TryGetValue(scopeKey, out string? initial))
+        {
+            return DeserializeStateAsync<T>(initial);
+        }
+
+        return ValueTask.FromResult<T?>(default);
+    }
+
+    /// <inheritdoc/>
+    public async ValueTask<T> ReadOrInitStateAsync<T>(
+        string key,
+        Func<T> initialStateFactory,
+        string? scopeName = null,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(key);
+        ArgumentNullException.ThrowIfNull(initialStateFactory);
+
+        // Cannot rely on `value is not null` because T? on an unconstrained generic
+        // parameter does not become Nullable<T> for value types — the null check is
+        // always true for types like int. Instead, check key existence directly.
+        if (this.HasStateKey(key, scopeName))
+        {
+            T? value = await this.ReadStateAsync<T>(key, scopeName, cancellationToken).ConfigureAwait(false);
+            if (value is not null)
+            {
+                return value;
+            }
+        }
+
+        T initialValue = initialStateFactory();
+        await this.QueueStateUpdateAsync(key, initialValue, scopeName, cancellationToken).ConfigureAwait(false);
+        return initialValue;
+    }
+
+    /// <inheritdoc/>
+    public ValueTask<HashSet<string>> ReadStateKeysAsync(
+        string? scopeName = null,
+        CancellationToken cancellationToken = default)
+    {
+        string scopePrefix = GetScopePrefix(scopeName);
+        int scopePrefixLength = scopePrefix.Length;
+        HashSet<string> keys = new(StringComparer.Ordinal);
+
+        bool scopeCleared = scopeName is null
+            ? this.ClearedScopes.Contains(DefaultScopeName)
+            : this.ClearedScopes.Contains(scopeName);
+
+        // Start with keys from initial state (skip if scope was cleared)
+        if (!scopeCleared)
+        {
+            foreach (string stateKey in this._initialState.Keys)
+            {
+                if (stateKey.StartsWith(scopePrefix, StringComparison.Ordinal))
+                {
+                    keys.Add(stateKey[scopePrefixLength..]);
+                }
+            }
+        }
+
+        // Merge local updates: add if non-null, remove if null (deleted)
+        foreach (KeyValuePair<string, string?> update in this.StateUpdates)
+        {
+            if (!update.Key.StartsWith(scopePrefix, StringComparison.Ordinal))
+            {
+                continue;
+            }
+
+            string key = update.Key[scopePrefixLength..];
+            if (update.Value is not null)
+            {
+                keys.Add(key);
+            }
+            else
+            {
+                keys.Remove(key);
+            }
+        }
+
+        return ValueTask.FromResult(keys);
+    }
+
+    /// <inheritdoc/>
+    public ValueTask QueueStateUpdateAsync<T>(
+        string key,
+        T? value,
+        string? scopeName = null,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(key);
+
+        string scopeKey = GetScopeKey(scopeName, key);
+        this.StateUpdates[scopeKey] = value is null ? null : SerializeState(value);
+        return default;
+    }
+
+    /// <inheritdoc/>
+    public ValueTask QueueClearScopeAsync(
+        string? scopeName = null,
+        CancellationToken cancellationToken = default)
+    {
+        this.ClearedScopes.Add(scopeName ?? DefaultScopeName);
+
+        // Remove any pending updates in this scope (snapshot keys to allow removal during iteration)
+        string scopePrefix = GetScopePrefix(scopeName);
+        foreach (string key in this.StateUpdates.Keys.ToList())
+        {
+            if (key.StartsWith(scopePrefix, StringComparison.Ordinal))
+            {
+                this.StateUpdates.Remove(key);
+            }
+        }
+
+        return default;
+    }
+
+    /// <inheritdoc/>
+    public IReadOnlyDictionary<string, string>? TraceContext => null;
+
+    /// <inheritdoc/>
+    public bool ConcurrentRunsEnabled => false;
+
+    private static string GetScopeKey(string? scopeName, string key)
+        => $"{GetScopePrefix(scopeName)}{key}";
+
+    /// <summary>
+    /// Checks whether the given key exists in local updates or initial state,
+    /// respecting cleared scopes.
+    /// </summary>
+    private bool HasStateKey(string key, string? scopeName)
+    {
+        string scopeKey = GetScopeKey(scopeName, key);
+
+        if (this.StateUpdates.TryGetValue(scopeKey, out string? updated))
+        {
+            return updated is not null;
+        }
+
+        string normalizedScope = scopeName ?? DefaultScopeName;
+        if (this.ClearedScopes.Contains(normalizedScope))
+        {
+            return false;
+        }
+
+        return this._initialState.ContainsKey(scopeKey);
+    }
+
+    /// <summary>
+    /// Returns the key prefix for the given scope. Scopes partition shared state
+    /// into logical namespaces, allowing different workflow executors to manage
+    /// their state keys independently. When no scope is specified, the
+    /// <see cref="DefaultScopeName"/> is used.
+    /// </summary>
+    private static string GetScopePrefix(string? scopeName)
+        => scopeName is null ? $"{DefaultScopeName}:" : $"{scopeName}:";
+
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Serializing workflow state types.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Serializing workflow state types.")]
+    private static string SerializeState<T>(T value)
+        => JsonSerializer.Serialize(value, DurableSerialization.Options);
+
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing workflow state types.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing workflow state types.")]
+    private static ValueTask<T?> DeserializeStateAsync<T>(string? json)
+    {
+        if (json is null)
+        {
+            return ValueTask.FromResult<T?>(default);
+        }
+
+        return ValueTask.FromResult(JsonSerializer.Deserialize<T>(json, DurableSerialization.Options));
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowFailedEvent.cs

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Event raised when a durable workflow fails.
+/// </summary>
+[DebuggerDisplay("Failed: {ErrorMessage}")]
+public sealed class DurableWorkflowFailedEvent : WorkflowEvent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableWorkflowFailedEvent"/> class.
+    /// </summary>
+    /// <param name="errorMessage">The error message describing the failure.</param>
+    /// <param name="failureDetails">The full failure details from the Durable Task runtime, if available.</param>
+    public DurableWorkflowFailedEvent(string errorMessage, TaskFailureDetails? failureDetails = null) : base(errorMessage)
+    {
+        this.ErrorMessage = errorMessage;
+        this.FailureDetails = failureDetails;
+    }
+
+    /// <summary>
+    /// Gets the error message describing the failure.
+    /// </summary>
+    public string ErrorMessage { get; }
+
+    /// <summary>
+    /// Gets the full failure details from the Durable Task runtime, including error type, stack trace, and inner failure.
+    /// </summary>
+    public TaskFailureDetails? FailureDetails { get; }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowInput.cs

@@ -0,0 +1,16 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Represents the input envelope for a durable workflow orchestration.
+/// </summary>
+/// <typeparam name="TInput">The type of the workflow input.</typeparam>
+internal sealed class DurableWorkflowInput<TInput>
+    where TInput : notnull
+{
+    /// <summary>
+    /// Gets the workflow input data.
+    /// </summary>
+    public required TInput Input { get; init; }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowJsonContext.cs

@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json.Serialization;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Source-generated JSON serialization context for durable workflow types.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This context provides AOT-compatible and trimmer-safe JSON serialization for the
+/// internal data transfer types used by the durable workflow infrastructure:
+/// </para>
+/// <list type="bullet">
+/// <item><description><see cref="DurableActivityInput"/>: Activity input wrapper with state</description></item>
+/// <item><description><see cref="DurableExecutorOutput"/>: Executor output wrapper with results, events, and state updates</description></item>
+/// <item><description><see cref="TypedPayload"/>: Serialized payload wrapper with type info (events and messages)</description></item>
+/// <item><description><see cref="DurableWorkflowLiveStatus"/>: Live status payload (streaming events and pending request ports)</description></item>
+/// </list>
+/// <para>
+/// Note: User-defined executor input/output types still use reflection-based serialization
+/// since their types are not known at compile time.
+/// </para>
+/// </remarks>
+[JsonSourceGenerationOptions(
+    WriteIndented = false,
+    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
+    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
+[JsonSerializable(typeof(DurableActivityInput))]
+[JsonSerializable(typeof(DurableExecutorOutput))]
+[JsonSerializable(typeof(TypedPayload))]
+[JsonSerializable(typeof(List<TypedPayload>))]
+[JsonSerializable(typeof(DurableWorkflowLiveStatus))]
+[JsonSerializable(typeof(DurableWorkflowResult))]
+[JsonSerializable(typeof(PendingRequestPortStatus))]
+[JsonSerializable(typeof(List<PendingRequestPortStatus>))]
+[JsonSerializable(typeof(List<string>))]
+[JsonSerializable(typeof(Dictionary<string, string>))]
+[JsonSerializable(typeof(Dictionary<string, string?>))]
+internal partial class DurableWorkflowJsonContext : JsonSerializerContext;

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowLiveStatus.cs

@@ -0,0 +1,59 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Live status payload written to the orchestration via <c>SetCustomStatus</c>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This is the only orchestration state readable by external clients while the workflow
+/// is still running. It is written after each superstep so that
+/// <see cref="DurableStreamingWorkflowRun"/> can poll for new events.
+/// On completion the framework clears it, so events are also
+/// embedded in the output via <see cref="DurableWorkflowResult"/>.
+/// </para>
+/// <para>
+/// When the workflow is paused at one or more <see cref="RequestPort"/> nodes,
+/// <see cref="PendingEvents"/> contains the request data for each.
+/// </para>
+/// </remarks>
+internal sealed class DurableWorkflowLiveStatus
+{
+    /// <summary>
+    /// Gets or sets the pending request ports the workflow is waiting on. Empty when no input is needed.
+    /// </summary>
+    public List<PendingRequestPortStatus> PendingEvents { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets the serialized workflow events emitted so far.
+    /// </summary>
+    public List<string> Events { get; set; } = [];
+
+    /// <summary>
+    /// Attempts to deserialize a serialized custom status string into a <see cref="DurableWorkflowLiveStatus"/>.
+    /// </summary>
+    [System.Diagnostics.CodeAnalysis.UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing durable workflow status.")]
+    [System.Diagnostics.CodeAnalysis.UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing durable workflow status.")]
+    internal static bool TryParse(string? serializedStatus, out DurableWorkflowLiveStatus result)
+    {
+        if (serializedStatus is null)
+        {
+            result = default!;
+            return false;
+        }
+
+        try
+        {
+            result = System.Text.Json.JsonSerializer.Deserialize<DurableWorkflowLiveStatus>(serializedStatus, DurableSerialization.Options)!;
+            return result is not null;
+        }
+        catch (System.Text.Json.JsonException)
+        {
+            result = default!;
+            return false;
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowOptions.cs

@@ -0,0 +1,111 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Provides configuration options for managing durable workflows within an application.
+/// </summary>
+[DebuggerDisplay("Workflows = {Workflows.Count}")]
+public sealed class DurableWorkflowOptions
+{
+    private readonly Dictionary<string, Workflow> _workflows = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableWorkflowOptions"/> class.
+    /// </summary>
+    /// <param name="parentOptions">Optional parent options container for accessing related configuration.</param>
+    internal DurableWorkflowOptions(DurableOptions? parentOptions = null)
+    {
+        this.ParentOptions = parentOptions;
+    }
+
+    /// <summary>
+    /// Gets the parent <see cref="DurableOptions"/> container, if available.
+    /// </summary>
+    internal DurableOptions? ParentOptions { get; }
+
+    /// <summary>
+    /// Gets the collection of workflows available in the current context, keyed by their unique names.
+    /// </summary>
+    public IReadOnlyDictionary<string, Workflow> Workflows => this._workflows;
+
+    /// <summary>
+    /// Gets the executor registry for direct executor lookup.
+    /// </summary>
+    internal ExecutorRegistry Executors { get; } = new();
+
+    /// <summary>
+    /// Adds a workflow to the collection for processing or execution.
+    /// </summary>
+    /// <param name="workflow">The workflow instance to add. Cannot be null.</param>
+    /// <remarks>
+    /// When a workflow is added, all executors are registered in the executor registry.
+    /// Any AI agent executors will also be automatically registered with the
+    /// <see cref="DurableAgentsOptions"/> if available.
+    /// </remarks>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="workflow"/> is null.</exception>
+    /// <exception cref="ArgumentException">Thrown when the workflow does not have a valid name.</exception>
+    public void AddWorkflow(Workflow workflow)
+    {
+        ArgumentNullException.ThrowIfNull(workflow);
+
+        if (string.IsNullOrEmpty(workflow.Name))
+        {
+            throw new ArgumentException("Workflow must have a valid Name property.", nameof(workflow));
+        }
+
+        this._workflows[workflow.Name] = workflow;
+        this.RegisterWorkflowExecutors(workflow);
+    }
+
+    /// <summary>
+    /// Adds a collection of workflows to the current instance.
+    /// </summary>
+    /// <param name="workflows">The collection of <see cref="Workflow"/> objects to add.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="workflows"/> is null.</exception>
+    public void AddWorkflows(params Workflow[] workflows)
+    {
+        ArgumentNullException.ThrowIfNull(workflows);
+
+        foreach (Workflow workflow in workflows)
+        {
+            this.AddWorkflow(workflow);
+        }
+    }
+
+    /// <summary>
+    /// Registers all executors from a workflow, including AI agents if agent options are available.
+    /// </summary>
+    private void RegisterWorkflowExecutors(Workflow workflow)
+    {
+        DurableAgentsOptions? agentOptions = this.ParentOptions?.Agents;
+
+        foreach ((string executorId, ExecutorBinding binding) in workflow.ReflectExecutors())
+        {
+            string executorName = WorkflowNamingHelper.GetExecutorName(executorId);
+            this.Executors.Register(executorName, executorId, workflow);
+
+            TryRegisterAgent(binding, agentOptions);
+        }
+    }
+
+    /// <summary>
+    /// Registers an AI agent with the agent options if the binding contains an unregistered agent.
+    /// </summary>
+    private static void TryRegisterAgent(ExecutorBinding binding, DurableAgentsOptions? agentOptions)
+    {
+        if (agentOptions is null)
+        {
+            return;
+        }
+
+        if (binding.RawValue is AIAgent { Name: not null } agent
+            && !agentOptions.ContainsAgent(agent.Name))
+        {
+            agentOptions.AddAIAgent(agent);
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowResult.cs

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Wraps the orchestration output to include both the workflow result and accumulated events.
+/// </summary>
+/// <remarks>
+/// The Durable Task framework clears <c>SerializedCustomStatus</c> when an orchestration
+/// completes. To ensure streaming clients can retrieve events even after completion,
+/// the accumulated events are embedded in the orchestration output alongside the result.
+/// </remarks>
+internal sealed class DurableWorkflowResult
+{
+    /// <summary>
+    /// Gets or sets the serialized result of the workflow execution.
+    /// </summary>
+    public string? Result { get; set; }
+
+    /// <summary>
+    /// Gets or sets the serialized workflow events emitted during execution.
+    /// </summary>
+    public List<string> Events { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets the typed messages to forward to connected executors in the parent workflow.
+    /// </summary>
+    /// <remarks>
+    /// When this workflow runs as a sub-orchestration, these messages are propagated to the
+    /// parent workflow and routed to successor executors via the edge map.
+    /// </remarks>
+    public List<TypedPayload> SentMessages { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the workflow was halted by an executor.
+    /// </summary>
+    /// <remarks>
+    /// When this workflow runs as a sub-orchestration, this flag is propagated to the
+    /// parent workflow so halt semantics are preserved across nesting levels.
+    /// </remarks>
+    public bool HaltRequested { get; set; }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowRun.cs

@@ -0,0 +1,116 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask;
+using Microsoft.DurableTask.Client;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Represents a durable workflow run that tracks execution status and provides access to workflow events.
+/// </summary>
+[DebuggerDisplay("{WorkflowName} ({RunId})")]
+internal sealed class DurableWorkflowRun : IAwaitableWorkflowRun
+{
+    private readonly DurableTaskClient _client;
+    private readonly List<WorkflowEvent> _eventSink = [];
+    private int _lastBookmark;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableWorkflowRun"/> class.
+    /// </summary>
+    /// <param name="client">The durable task client for orchestration operations.</param>
+    /// <param name="instanceId">The unique instance ID for this orchestration run.</param>
+    /// <param name="workflowName">The name of the workflow being executed.</param>
+    internal DurableWorkflowRun(DurableTaskClient client, string instanceId, string workflowName)
+    {
+        this._client = client;
+        this.RunId = instanceId;
+        this.WorkflowName = workflowName;
+    }
+
+    /// <inheritdoc/>
+    public string RunId { get; }
+
+    /// <summary>
+    /// Gets the name of the workflow being executed.
+    /// </summary>
+    public string WorkflowName { get; }
+
+    /// <summary>
+    /// Waits for the workflow to complete and returns the result.
+    /// </summary>
+    /// <typeparam name="TResult">The expected result type.</typeparam>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>The result of the workflow execution.</returns>
+    /// <exception cref="TaskFailedException">Thrown when the workflow failed.</exception>
+    /// <exception cref="InvalidOperationException">Thrown when the workflow was terminated or ended with an unexpected status.</exception>
+    public async ValueTask<TResult?> WaitForCompletionAsync<TResult>(CancellationToken cancellationToken = default)
+    {
+        OrchestrationMetadata metadata = await this._client.WaitForInstanceCompletionAsync(
+            this.RunId,
+            getInputsAndOutputs: true,
+            cancellation: cancellationToken).ConfigureAwait(false);
+
+        if (metadata.RuntimeStatus == OrchestrationRuntimeStatus.Completed)
+        {
+            return DurableStreamingWorkflowRun.ExtractResult<TResult>(metadata.SerializedOutput);
+        }
+
+        if (metadata.RuntimeStatus == OrchestrationRuntimeStatus.Failed)
+        {
+            if (metadata.FailureDetails is not null)
+            {
+                // Use TaskFailedException to preserve full failure details including stack trace and inner exceptions
+                throw new TaskFailedException(
+                    taskName: this.WorkflowName,
+                    taskId: 0,
+                    failureDetails: metadata.FailureDetails);
+            }
+
+            throw new InvalidOperationException(
+                $"Workflow '{this.WorkflowName}' (RunId: {this.RunId}) failed without failure details.");
+        }
+
+        throw new InvalidOperationException(
+            $"Workflow '{this.WorkflowName}' (RunId: {this.RunId}) ended with unexpected status: {metadata.RuntimeStatus}");
+    }
+
+    /// <summary>
+    /// Waits for the workflow to complete and returns the string result.
+    /// </summary>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>The string result of the workflow execution.</returns>
+    public ValueTask<string?> WaitForCompletionAsync(CancellationToken cancellationToken = default)
+        => this.WaitForCompletionAsync<string>(cancellationToken);
+
+    /// <summary>
+    /// Gets all events that have been collected from the workflow.
+    /// </summary>
+    public IEnumerable<WorkflowEvent> OutgoingEvents => this._eventSink;
+
+    /// <summary>
+    /// Gets the number of events collected since the last access to <see cref="NewEvents"/>.
+    /// </summary>
+    public int NewEventCount => this._eventSink.Count - this._lastBookmark;
+
+    /// <summary>
+    /// Gets all events collected since the last access to <see cref="NewEvents"/>.
+    /// </summary>
+    public IEnumerable<WorkflowEvent> NewEvents
+    {
+        get
+        {
+            if (this._lastBookmark >= this._eventSink.Count)
+            {
+                return [];
+            }
+
+            int currentBookmark = this._lastBookmark;
+            this._lastBookmark = this._eventSink.Count;
+
+            return this._eventSink.Skip(currentBookmark);
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowRunner.cs

@@ -0,0 +1,619 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// ConfigureAwait Usage in Orchestration Code:
+// This file uses ConfigureAwait(true) because it runs within orchestration context.
+// Durable Task orchestrations require deterministic replay - the same code must execute
+// identically across replays. ConfigureAwait(true) ensures continuations run on the
+// orchestration's synchronization context, which is essential for replay correctness.
+// Using ConfigureAwait(false) here could cause non-deterministic behavior during replay.
+
+// Superstep execution walkthrough for a workflow like below:
+//
+//     [A] ──► [B] ──► [C] ──► [E]          (B→D has condition: x => x.NeedsReview)
+//              │               ▲
+//              └──► [D] ──────┘
+//
+//  Superstep 1 — A runs
+//    Queues before:  A:[input]                   Results: {}
+//    Dispatch:       A executes, returns resultA
+//    Route:          EdgeMap routes A's output → B's queue
+//    Queues after:   B:[resultA]                 Results: {A: resultA}
+//
+//  Superstep 2 — B runs
+//    Queues before:  B:[resultA]                 Results: {A: resultA}
+//    Dispatch:       B executes, returns resultB (type: Order)
+//    Route:          FanOutRouter sends resultB to:
+//                      C's queue (unconditional)
+//                      D's queue (only if resultB.NeedsReview == true)
+//    Queues after:   C:[resultB], D:[resultB]    Results: {A: .., B: resultB}
+//                    (D may be empty if condition was false)
+//
+//  Superstep 3 — C and D run in parallel
+//    Queues before:  C:[resultB], D:[resultB]
+//    Dispatch:       C and D execute concurrently via Task.WhenAll
+//    Route:          Both route output → E's queue
+//    Queues after:   E:[resultC, resultD]        Results: {.., C: resultC, D: resultD}
+//
+//  Superstep 4 — E runs (fan-in)
+//    Queues before:  E:[resultC, resultD]        ◄── IsFanInExecutor("E") = true
+//    Collect:        AggregateQueueMessages merges into JSON array ["resultC","resultD"]
+//    Dispatch:       E executes with aggregated input
+//    Route:          E has no successors → nothing enqueued
+//    Queues after:   (all empty)                 Results: {.., E: resultE}
+//
+//  Superstep 5 — loop exits (no pending messages)
+//    GetFinalResult returns resultE
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
+using Microsoft.Agents.AI.DurableTask.Workflows.EdgeRouters;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.DurableTask;
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+// Superstep loop:
+//
+//  ┌───────────────┐    ┌───────────────┐    ┌───────────────────┐
+//  │ Collect       │───►│ Dispatch      │───►│ Process Results   │
+//  │ Executor      │    │ Executors     │    │ & Route Messages  │
+//  │ Inputs        │    │ in Parallel   │    │                   │
+//  └───────────────┘    └───────────────┘    └───────────────────┘
+//         ▲                                           │
+//         └───────────────────────────────────────────┘
+//                    (repeat until no pending messages)
+
+/// <summary>
+/// Runs workflow orchestrations using message-driven superstep execution with Durable Task.
+/// </summary>
+internal sealed class DurableWorkflowRunner
+{
+    private const int MaxSupersteps = 100;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="DurableWorkflowRunner"/> class.
+    /// </summary>
+    /// <param name="durableOptions">The durable options containing workflow configurations.</param>
+    public DurableWorkflowRunner(DurableOptions durableOptions)
+    {
+        ArgumentNullException.ThrowIfNull(durableOptions);
+
+        this.Options = durableOptions.Workflows;
+    }
+
+    /// <summary>
+    /// Gets the workflow options.
+    /// </summary>
+    private DurableWorkflowOptions Options { get; }
+
+    /// <summary>
+    /// Runs a workflow orchestration.
+    /// </summary>
+    /// <param name="context">The task orchestration context.</param>
+    /// <param name="workflowInput">The workflow input envelope containing workflow input and metadata.</param>
+    /// <param name="logger">The replay-safe logger for orchestration logging.</param>
+    /// <returns>The result of the workflow execution.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the specified workflow is not found.</exception>
+    internal async Task<DurableWorkflowResult> RunWorkflowOrchestrationAsync(
+        TaskOrchestrationContext context,
+        DurableWorkflowInput<object> workflowInput,
+        ILogger logger)
+    {
+        ArgumentNullException.ThrowIfNull(context);
+        ArgumentNullException.ThrowIfNull(workflowInput);
+
+        Workflow workflow = this.GetWorkflowOrThrow(context.Name);
+
+        string workflowName = context.Name;
+        string instanceId = context.InstanceId;
+        logger.LogWorkflowStarting(workflowName, instanceId);
+
+        WorkflowGraphInfo graphInfo = WorkflowAnalyzer.BuildGraphInfo(workflow);
+        DurableEdgeMap edgeMap = new(graphInfo);
+
+        // Extract input - the start executor determines the expected input type from its own InputTypes
+        object input = workflowInput.Input;
+
+        return await RunSuperstepLoopAsync(context, workflow, edgeMap, input, logger).ConfigureAwait(true);
+    }
+
+    private Workflow GetWorkflowOrThrow(string orchestrationName)
+    {
+        string workflowName = WorkflowNamingHelper.ToWorkflowName(orchestrationName);
+
+        if (!this.Options.Workflows.TryGetValue(workflowName, out Workflow? workflow))
+        {
+            throw new InvalidOperationException($"Workflow '{workflowName}' not found.");
+        }
+
+        return workflow;
+    }
+
+    /// <summary>
+    /// Runs the workflow execution loop using superstep-based processing.
+    /// </summary>
+    [UnconditionalSuppressMessage("AOT", "IL2026:RequiresUnreferencedCode", Justification = "Input types are preserved by the Durable Task framework's DataConverter.")]
+    [UnconditionalSuppressMessage("AOT", "IL3050:RequiresDynamicCode", Justification = "Input types are preserved by the Durable Task framework's DataConverter.")]
+    private static async Task<DurableWorkflowResult> RunSuperstepLoopAsync(
+        TaskOrchestrationContext context,
+        Workflow workflow,
+        DurableEdgeMap edgeMap,
+        object initialInput,
+        ILogger logger)
+    {
+        SuperstepState state = new(workflow, edgeMap);
+
+        // Convert input to string for the message queue.
+        // When DurableWorkflowInput<string> is deserialized as DurableWorkflowInput<object>,
+        // the Input property becomes a JsonElement instead of a string.
+        // We must extract the raw string value to avoid double-serialization.
+        string inputString = initialInput switch
+        {
+            string s => s,
+            JsonElement je when je.ValueKind == JsonValueKind.String => je.GetString() ?? string.Empty,
+            _ => JsonSerializer.Serialize(initialInput)
+        };
+
+        edgeMap.EnqueueInitialInput(inputString, state.MessageQueues);
+
+        bool haltRequested = false;
+
+        for (int superstep = 1; superstep <= MaxSupersteps; superstep++)
+        {
+            List<ExecutorInput> executorInputs = CollectExecutorInputs(state, logger);
+            if (executorInputs.Count == 0)
+            {
+                break;
+            }
+
+            logger.LogSuperstepStarting(superstep, executorInputs.Count);
+            if (logger.IsEnabled(LogLevel.Debug))
+            {
+                logger.LogSuperstepExecutors(superstep, string.Join(", ", executorInputs.Select(e => e.ExecutorId)));
+            }
+
+            string[] results = await DispatchExecutorsInParallelAsync(context, executorInputs, state, logger).ConfigureAwait(true);
+
+            haltRequested = ProcessSuperstepResults(executorInputs, results, state, context, logger);
+
+            if (haltRequested)
+            {
+                break;
+            }
+
+            // Check if we've reached the limit and still have work remaining
+            int remainingExecutors = CountRemainingExecutors(state.MessageQueues);
+            if (superstep == MaxSupersteps && remainingExecutors > 0)
+            {
+                logger.LogWorkflowMaxSuperstepsExceeded(context.InstanceId, MaxSupersteps, remainingExecutors);
+            }
+        }
+
+        // Publish final events for live streaming (skip during replay)
+        if (!context.IsReplaying)
+        {
+            PublishEventsToLiveStatus(context, state);
+        }
+
+        string finalResult = GetFinalResult(state.LastResults);
+        logger.LogWorkflowCompleted();
+
+        // Return wrapper with both result and events so streaming clients can
+        // retrieve events from SerializedOutput after the orchestration completes
+        // (SerializedCustomStatus is cleared by the framework on completion).
+        // SentMessages carries the final result so parent workflows can route it
+        // to connected executors, matching the in-process WorkflowHostExecutor behavior.
+        return new DurableWorkflowResult
+        {
+            Result = finalResult,
+            Events = state.AccumulatedEvents,
+            SentMessages = !string.IsNullOrEmpty(finalResult)
+                ? [new TypedPayload { Data = finalResult }]
+                : [],
+            HaltRequested = haltRequested
+        };
+    }
+
+    /// <summary>
+    /// Counts the number of executors with pending messages in their queues.
+    /// </summary>
+    private static int CountRemainingExecutors(Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues)
+    {
+        return messageQueues.Count(kvp => kvp.Value.Count > 0);
+    }
+
+    private static async Task<string[]> DispatchExecutorsInParallelAsync(
+        TaskOrchestrationContext context,
+        List<ExecutorInput> executorInputs,
+        SuperstepState state,
+        ILogger logger)
+    {
+        Task<string>[] dispatchTasks = executorInputs
+            .Select(input => DurableExecutorDispatcher.DispatchAsync(context, input.Info, input.Envelope, state.SharedState, state.LiveStatus, logger))
+            .ToArray();
+
+        return await Task.WhenAll(dispatchTasks).ConfigureAwait(true);
+    }
+
+    /// <summary>
+    /// Holds state that accumulates and changes across superstep iterations during workflow execution.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <c>MessageQueues</c> starts with one entry (the start executor's queue, seeded by
+    /// <see cref="DurableEdgeMap.EnqueueInitialInput"/>). After each superstep, <c>RouteOutputToSuccessors</c>
+    /// adds entries for successor executors that receive routed messages. Queues are drained during
+    /// <c>CollectExecutorInputs</c>; empty queues are skipped.
+    /// </para>
+    /// <para>
+    /// <c>LastResults</c> is updated after every superstep with the result of each executor that ran.
+    /// At workflow completion, the last non-empty value is returned as the workflow's final result.
+    /// </para>
+    /// </remarks>
+    private sealed class SuperstepState
+    {
+        public SuperstepState(Workflow workflow, DurableEdgeMap edgeMap)
+        {
+            this.EdgeMap = edgeMap;
+            this.ExecutorBindings = workflow.ReflectExecutors();
+        }
+
+        public DurableEdgeMap EdgeMap { get; }
+
+        public Dictionary<string, ExecutorBinding> ExecutorBindings { get; }
+
+        public Dictionary<string, Queue<DurableMessageEnvelope>> MessageQueues { get; } = [];
+
+        public Dictionary<string, string> LastResults { get; } = [];
+
+        /// <summary>
+        /// Shared state dictionary across supersteps (scope-prefixed key -> serialized value).
+        /// </summary>
+        public Dictionary<string, string> SharedState { get; } = [];
+
+        /// <summary>
+        /// Accumulated workflow events for the durable workflow status (streaming consumption).
+        /// </summary>
+        public List<string> AccumulatedEvents { get; } = [];
+
+        /// <summary>
+        /// Workflow status published via <c>SetCustomStatus</c> so external clients can poll for streaming events and pending HITL requests.
+        /// </summary>
+        public DurableWorkflowLiveStatus LiveStatus { get; } = new();
+    }
+
+    /// <summary>
+    /// Represents prepared input for an executor ready for dispatch.
+    /// </summary>
+    private sealed record ExecutorInput(string ExecutorId, DurableMessageEnvelope Envelope, WorkflowExecutorInfo Info);
+
+    /// <summary>
+    /// Collects inputs for all active executors, applying Fan-In aggregation where needed.
+    /// </summary>
+    private static List<ExecutorInput> CollectExecutorInputs(
+        SuperstepState state,
+        ILogger logger)
+    {
+        List<ExecutorInput> inputs = [];
+
+        // Only process queues that have pending messages
+        foreach ((string executorId, Queue<DurableMessageEnvelope> queue) in state.MessageQueues
+            .Where(kvp => kvp.Value.Count > 0))
+        {
+            DurableMessageEnvelope envelope = GetNextEnvelope(executorId, queue, state.EdgeMap, logger);
+            WorkflowExecutorInfo executorInfo = CreateExecutorInfo(executorId, state.ExecutorBindings);
+
+            inputs.Add(new ExecutorInput(executorId, envelope, executorInfo));
+        }
+
+        return inputs;
+    }
+
+    private static DurableMessageEnvelope GetNextEnvelope(
+        string executorId,
+        Queue<DurableMessageEnvelope> queue,
+        DurableEdgeMap edgeMap,
+        ILogger logger)
+    {
+        bool shouldAggregate = edgeMap.IsFanInExecutor(executorId) && queue.Count > 1;
+
+        return shouldAggregate
+            ? AggregateQueueMessages(queue, executorId, logger)
+            : queue.Dequeue();
+    }
+
+    /// <summary>
+    /// Aggregates all messages in a queue into a JSON array for Fan-In executors.
+    /// </summary>
+    private static DurableMessageEnvelope AggregateQueueMessages(
+        Queue<DurableMessageEnvelope> queue,
+        string executorId,
+        ILogger logger)
+    {
+        List<string> messages = [];
+        List<string> sourceIds = [];
+
+        while (queue.Count > 0)
+        {
+            DurableMessageEnvelope envelope = queue.Dequeue();
+            messages.Add(envelope.Message);
+
+            if (envelope.SourceExecutorId is not null)
+            {
+                sourceIds.Add(envelope.SourceExecutorId);
+            }
+        }
+
+        if (logger.IsEnabled(LogLevel.Debug))
+        {
+            logger.LogFanInAggregated(executorId, messages.Count, string.Join(", ", sourceIds));
+        }
+
+        return new DurableMessageEnvelope
+        {
+            Message = SerializeToJsonArray(messages),
+            InputTypeName = typeof(string[]).FullName,
+            SourceExecutorId = sourceIds.Count > 0 ? string.Join(",", sourceIds) : null
+        };
+    }
+
+    /// <summary>
+    /// Processes results from a superstep, updating state and routing messages to successors.
+    /// </summary>
+    /// <returns><c>true</c> if a halt was requested by any executor; otherwise, <c>false</c>.</returns>
+    private static bool ProcessSuperstepResults(
+        List<ExecutorInput> inputs,
+        string[] rawResults,
+        SuperstepState state,
+        TaskOrchestrationContext context,
+        ILogger logger)
+    {
+        bool haltRequested = false;
+
+        for (int i = 0; i < inputs.Count; i++)
+        {
+            string executorId = inputs[i].ExecutorId;
+            ExecutorResultInfo resultInfo = ParseActivityResult(rawResults[i]);
+
+            logger.LogExecutorResultReceived(executorId, resultInfo.Result.Length, resultInfo.SentMessages.Count);
+
+            state.LastResults[executorId] = resultInfo.Result;
+
+            // Merge state updates from activity into shared state
+            MergeStateUpdates(state, resultInfo.StateUpdates, resultInfo.ClearedScopes);
+
+            // Accumulate events for the durable workflow status (streaming)
+            state.AccumulatedEvents.AddRange(resultInfo.Events);
+
+            // Check for halt request
+            haltRequested |= resultInfo.HaltRequested;
+
+            // Publish events for live streaming (skip during replay)
+            if (!context.IsReplaying)
+            {
+                PublishEventsToLiveStatus(context, state);
+            }
+
+            RouteOutputToSuccessors(executorId, resultInfo.Result, resultInfo.SentMessages, state, logger);
+        }
+
+        return haltRequested;
+    }
+
+    /// <summary>
+    /// Merges state updates from an executor into the shared state.
+    /// </summary>
+    /// <remarks>
+    /// When concurrent executors in the same superstep modify keys in the same scope,
+    /// last-write-wins semantics apply.
+    /// </remarks>
+    private static void MergeStateUpdates(
+        SuperstepState state,
+        Dictionary<string, string?> stateUpdates,
+        List<string> clearedScopes)
+    {
+        Dictionary<string, string> shared = state.SharedState;
+
+        ApplyClearedScopes(shared, clearedScopes);
+
+        // Apply individual state updates
+        foreach ((string key, string? value) in stateUpdates)
+        {
+            if (value is null)
+            {
+                shared.Remove(key);
+            }
+            else
+            {
+                shared[key] = value;
+            }
+        }
+    }
+
+    /// <summary>
+    /// Removes all keys belonging to the specified scopes from the shared state dictionary.
+    /// </summary>
+    private static void ApplyClearedScopes(Dictionary<string, string> shared, List<string> clearedScopes)
+    {
+        if (clearedScopes.Count == 0 || shared.Count == 0)
+        {
+            return;
+        }
+
+        List<string> keysToRemove = [];
+
+        foreach (string clearedScope in clearedScopes)
+        {
+            string scopePrefix = string.Concat(clearedScope, ":");
+            keysToRemove.Clear();
+
+            foreach (string key in shared.Keys)
+            {
+                if (key.StartsWith(scopePrefix, StringComparison.Ordinal))
+                {
+                    keysToRemove.Add(key);
+                }
+            }
+
+            foreach (string key in keysToRemove)
+            {
+                shared.Remove(key);
+            }
+
+            if (shared.Count == 0)
+            {
+                break;
+            }
+        }
+    }
+
+    /// <summary>
+    /// Publishes accumulated workflow events to the durable workflow's custom status,
+    /// making them available to <see cref="DurableStreamingWorkflowRun"/> for live streaming.
+    /// </summary>
+    /// <remarks>
+    /// Custom status is the only orchestration state readable by external clients while
+    /// the orchestration is still running. It is cleared by the framework on completion,
+    /// so events are also included in <see cref="DurableWorkflowResult"/> for final retrieval.
+    /// </remarks>
+    private static void PublishEventsToLiveStatus(
+        TaskOrchestrationContext context,
+        SuperstepState state)
+    {
+        state.LiveStatus.Events = state.AccumulatedEvents;
+
+        // Pass the object directly — the framework's DataConverter handles serialization.
+        // Pre-serializing would cause double-serialization (string wrapped in JSON quotes).
+        context.SetCustomStatus(state.LiveStatus);
+    }
+
+    /// <summary>
+    /// Routes executor output (explicit messages or return value) to successor executors.
+    /// </summary>
+    private static void RouteOutputToSuccessors(
+        string executorId,
+        string result,
+        List<TypedPayload> sentMessages,
+        SuperstepState state,
+        ILogger logger)
+    {
+        if (sentMessages.Count > 0)
+        {
+            // Only route messages that have content
+            foreach (TypedPayload message in sentMessages.Where(m => !string.IsNullOrEmpty(m.Data)))
+            {
+                state.EdgeMap.RouteMessage(executorId, message.Data!, message.TypeName, state.MessageQueues, logger);
+            }
+
+            return;
+        }
+
+        if (!string.IsNullOrEmpty(result))
+        {
+            state.EdgeMap.RouteMessage(executorId, result, inputTypeName: null, state.MessageQueues, logger);
+        }
+    }
+
+    /// <summary>
+    /// Serializes a list of messages into a JSON array.
+    /// </summary>
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Serializing string array.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Serializing string array.")]
+    private static string SerializeToJsonArray(List<string> messages)
+    {
+        return JsonSerializer.Serialize(messages);
+    }
+
+    /// <summary>
+    /// Creates a <see cref="WorkflowExecutorInfo"/> for the given executor ID.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Thrown when the executor ID is not found in bindings.</exception>
+    private static WorkflowExecutorInfo CreateExecutorInfo(
+        string executorId,
+        Dictionary<string, ExecutorBinding> executorBindings)
+    {
+        if (!executorBindings.TryGetValue(executorId, out ExecutorBinding? binding))
+        {
+            throw new InvalidOperationException($"Executor '{executorId}' not found in workflow bindings.");
+        }
+
+        bool isAgentic = WorkflowAnalyzer.IsAgentExecutorType(binding.ExecutorType);
+        RequestPort? requestPort = (binding is RequestPortBinding rpb) ? rpb.Port : null;
+        Workflow? subWorkflow = (binding is SubworkflowBinding swb) ? swb.WorkflowInstance : null;
+
+        return new WorkflowExecutorInfo(executorId, isAgentic, requestPort, subWorkflow);
+    }
+
+    /// <summary>
+    /// Returns the last non-empty result from executed steps, or empty string if none.
+    /// </summary>
+    private static string GetFinalResult(Dictionary<string, string> lastResults)
+    {
+        return lastResults.Values.LastOrDefault(value => !string.IsNullOrEmpty(value)) ?? string.Empty;
+    }
+
+    /// <summary>
+    /// Output from an executor invocation, including its result,
+    /// messages, state updates, and emitted workflow events.
+    /// </summary>
+    private sealed record ExecutorResultInfo(
+        string Result,
+        List<TypedPayload> SentMessages,
+        Dictionary<string, string?> StateUpdates,
+        List<string> ClearedScopes,
+        List<string> Events,
+        bool HaltRequested);
+
+    /// <summary>
+    /// Parses the raw activity result to extract result, messages, events, and state updates.
+    /// </summary>
+    private static ExecutorResultInfo ParseActivityResult(string rawResult)
+    {
+        if (string.IsNullOrEmpty(rawResult))
+        {
+            return new ExecutorResultInfo(rawResult, [], [], [], [], false);
+        }
+
+        try
+        {
+            DurableExecutorOutput? output = JsonSerializer.Deserialize(
+                rawResult,
+                DurableWorkflowJsonContext.Default.DurableExecutorOutput);
+
+            if (output is null || !HasMeaningfulContent(output))
+            {
+                return new ExecutorResultInfo(rawResult, [], [], [], [], false);
+            }
+
+            return new ExecutorResultInfo(
+                output.Result ?? string.Empty,
+                output.SentMessages,
+                output.StateUpdates,
+                output.ClearedScopes,
+                output.Events,
+                output.HaltRequested);
+        }
+        catch (JsonException)
+        {
+            return new ExecutorResultInfo(rawResult, [], [], [], [], false);
+        }
+    }
+
+    /// <summary>
+    /// Determines whether the activity output contains meaningful content.
+    /// </summary>
+    /// <remarks>
+    /// Distinguishes actual activity output from arbitrary JSON that deserialized
+    /// successfully but with all default/empty values.
+    /// </remarks>
+    private static bool HasMeaningfulContent(DurableExecutorOutput output)
+    {
+        return output.Result is not null
+            || output.SentMessages?.Count > 0
+            || output.Events?.Count > 0
+            || output.StateUpdates?.Count > 0
+            || output.ClearedScopes?.Count > 0
+            || output.HaltRequested;
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/DurableWorkflowWaitingForInputEvent.cs

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Event raised when the durable workflow is waiting for external input at a <see cref="RequestPort"/>.
+/// </summary>
+/// <param name="Input">The serialized input data that was passed to the RequestPort.</param>
+/// <param name="RequestPort">The request port definition.</param>
+[DebuggerDisplay("RequestPort = {RequestPort.Id}")]
+public sealed class DurableWorkflowWaitingForInputEvent(
+    string Input,
+    RequestPort RequestPort) : WorkflowEvent
+{
+    /// <summary>
+    /// Gets the serialized input data that was passed to the RequestPort.
+    /// </summary>
+    public string Input { get; } = Input;
+
+    /// <summary>
+    /// Gets the request port definition.
+    /// </summary>
+    public RequestPort RequestPort { get; } = RequestPort;
+
+    /// <summary>
+    /// Attempts to deserialize the input data to the specified type.
+    /// </summary>
+    /// <typeparam name="T">The type to deserialize to.</typeparam>
+    /// <returns>The deserialized input.</returns>
+    /// <exception cref="JsonException">Thrown when the input cannot be deserialized to the specified type.</exception>
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing workflow types provided by the caller.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing workflow types provided by the caller.")]
+    public T? GetInputAs<T>()
+    {
+        return JsonSerializer.Deserialize<T>(this.Input, DurableSerialization.Options);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/EdgeRouters/DurableDirectEdgeRouter.cs

@@ -0,0 +1,156 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Routing decision flow for a single edge.
+// Example: the B→D edge from a workflow like below:
+//
+//     [A] ──► [B] ──► [C] ──► [E]          (B→D has condition: x => x.NeedsReview)
+//              │               ▲
+//              └──► [D] ──────┘
+//
+//   (condition: x => x.NeedsReview, _sourceOutputType: typeof(Order))
+//
+//  RouteMessage(envelope)          envelope.Message = "{\"NeedsReview\":true, ...}"
+//       │
+//       ▼
+//  Has condition? ──── No ────► Enqueue to sink's queue
+//       │
+//      Yes  (B→D has one)
+//       │
+//       ▼
+//  Deserialize message             JSON string → Order object using _sourceOutputType
+//       │
+//       ▼
+//  Evaluate _condition(order)      order => order.NeedsReview
+//       │
+//    ┌──┴──┐
+//  true   false
+//    │      │
+//    ▼      └──► Skip (log and return, D will not run)
+//  Enqueue to
+//  D's queue
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows.EdgeRouters;
+
+/// <summary>
+/// Routes messages from a source executor to a single target executor with optional condition evaluation.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Created by <see cref="DurableEdgeMap"/> during construction — one instance per (source, sink) edge.
+/// When an edge has a condition (e.g., <c>order =&gt; order.Total &gt; 1000</c>), the router deserialises
+/// the serialised JSON message back to the source executor's output type so the condition delegate
+/// can evaluate it against strongly-typed properties. If the condition returns <c>false</c>, the
+/// message is not forwarded and the target executor will not run for this edge.
+/// </para>
+/// <para>
+/// For sources with multiple successors, individual <see cref="DurableDirectEdgeRouter"/> instances
+/// are wrapped in a <see cref="DurableFanOutEdgeRouter"/> so a single <c>RouteMessage</c> call
+/// fans the same message out to all targets, each evaluating its own condition independently.
+/// </para>
+/// </remarks>
+internal sealed class DurableDirectEdgeRouter : IDurableEdgeRouter
+{
+    private readonly string _sourceId;
+    private readonly string _sinkId;
+    private readonly Func<object?, bool>? _condition;
+    private readonly Type? _sourceOutputType;
+
+    /// <summary>
+    /// Initializes a new instance of <see cref="DurableDirectEdgeRouter"/>.
+    /// </summary>
+    /// <param name="sourceId">The source executor ID.</param>
+    /// <param name="sinkId">The target executor ID.</param>
+    /// <param name="condition">Optional condition function to evaluate before routing.</param>
+    /// <param name="sourceOutputType">The output type of the source executor for deserialization.</param>
+    internal DurableDirectEdgeRouter(
+        string sourceId,
+        string sinkId,
+        Func<object?, bool>? condition,
+        Type? sourceOutputType)
+    {
+        this._sourceId = sourceId;
+        this._sinkId = sinkId;
+        this._condition = condition;
+        this._sourceOutputType = sourceOutputType;
+    }
+
+    /// <inheritdoc />
+    public void RouteMessage(
+        DurableMessageEnvelope envelope,
+        Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues,
+        ILogger logger)
+    {
+        if (this._condition is not null)
+        {
+            try
+            {
+                object? messageObj = DeserializeForCondition(envelope.Message, this._sourceOutputType);
+                if (!this._condition(messageObj))
+                {
+                    logger.LogEdgeConditionFalse(this._sourceId, this._sinkId);
+                    return;
+                }
+            }
+            catch (Exception ex)
+            {
+                logger.LogEdgeConditionEvaluationFailed(ex, this._sourceId, this._sinkId);
+                return;
+            }
+        }
+
+        logger.LogEdgeRoutingMessage(this._sourceId, this._sinkId);
+        EnqueueMessage(messageQueues, this._sinkId, envelope);
+    }
+
+    /// <summary>
+    /// Deserializes a JSON message to an object for condition evaluation.
+    /// </summary>
+    /// <remarks>
+    /// Messages travel through the durable workflow as serialized JSON strings, but condition
+    /// delegates need typed objects to evaluate (e.g., order => order.Status == "Approved").
+    /// This method converts the JSON back to an object the condition delegate can evaluate.
+    /// </remarks>
+    /// <param name="json">The JSON string representation of the message.</param>
+    /// <param name="targetType">
+    /// The expected type of the message. When provided, enables strongly-typed deserialization
+    /// so the condition function receives the correct type to evaluate against.
+    /// </param>
+    /// <returns>
+    /// The deserialized object, or null if the JSON is empty.
+    /// </returns>
+    /// <exception cref="JsonException">Thrown when the JSON is invalid or cannot be deserialized to the target type.</exception>
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing workflow types registered at startup.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing workflow types registered at startup.")]
+    private static object? DeserializeForCondition(string json, Type? targetType)
+    {
+        if (string.IsNullOrEmpty(json))
+        {
+            return null;
+        }
+
+        // If we know the source executor's output type, deserialize to that specific type
+        // so the condition function can access strongly-typed properties.
+        // Otherwise, deserialize as a generic object for basic inspection.
+        return targetType is null
+            ? JsonSerializer.Deserialize<object>(json, DurableSerialization.Options)
+            : JsonSerializer.Deserialize(json, targetType, DurableSerialization.Options);
+    }
+
+    private static void EnqueueMessage(
+        Dictionary<string, Queue<DurableMessageEnvelope>> queues,
+        string executorId,
+        DurableMessageEnvelope envelope)
+    {
+        if (!queues.TryGetValue(executorId, out Queue<DurableMessageEnvelope>? queue))
+        {
+            queue = new Queue<DurableMessageEnvelope>();
+            queues[executorId] = queue;
+        }
+
+        queue.Enqueue(envelope);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/EdgeRouters/DurableEdgeMap.cs

@@ -0,0 +1,205 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// How WorkflowGraphInfo maps to DurableEdgeMap at runtime.
+// For a workflow like below:
+//
+//     [A] ──► [B] ──► [C] ──► [E]
+//              │               ▲
+//              └──► [D] ──────┘
+//                (condition: x => x.NeedsReview)
+//
+//  WorkflowGraphInfo                          DurableEdgeMap
+//  ┌──────────────────────────┐               ┌──────────────────────────────────────┐
+//  │ Successors:              │               │ _routersBySource:                    │
+//  │   A → [B]                │──constructs──►│   A → [DirectRouter(A→B)]            │
+//  │   B → [C, D]             │               │   B → [FanOutRouter([C, D])]         │
+//  │   C → [E]                │               │   C → [DirectRouter(C→E)]            │
+//  │   D → [E]                │               │   D → [DirectRouter(D→E)]            │
+//  └──────────────────────────┘               │                                      │
+//  ┌──────────────────────────┐               │ _predecessorCounts:                  │
+//  │ Predecessors:            │               │   A → 0                              │
+//  │   E → [C, D]  (fan-in!)  │──constructs──►│   B → 1, C → 1, D → 1                │
+//  └──────────────────────────┘               │   E → 2  ◄── IsFanInExecutor = true  │
+//                                             └──────────────────────────────────────┘
+//
+// Usage during superstep execution (continuing the example):
+//
+//  1. EnqueueInitialInput(msg) ──► MessageQueues["A"].Enqueue(envelope)
+//
+//  2. After B completes, RouteMessage("B", resultB) ──► _routersBySource["B"]
+//       │
+//       ▼
+//     FanOutRouter (B has 2 successors)
+//       ├─► DirectRouter(B→C)  ──► no condition  ──► enqueue to C
+//       └─► DirectRouter(B→D)  ──► evaluate x => x.NeedsReview ──► enqueue to D (or skip)
+//
+//  3. Before superstep 4, IsFanInExecutor("E") returns true (count=2)
+//       → CollectExecutorInputs aggregates C and D results into ["resultC","resultD"]
+
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows.EdgeRouters;
+
+/// <summary>
+/// Manages message routing through workflow edges for durable orchestrations.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This is the durable equivalent of <c>EdgeMap</c> in the in-process runner.
+/// It is constructed from <see cref="WorkflowGraphInfo"/> (produced by <see cref="WorkflowAnalyzer.BuildGraphInfo"/>)
+/// and converts the static graph structure into an active routing layer used during superstep execution.
+/// </para>
+/// <para>
+/// <b>What it stores:</b>
+/// </para>
+/// <list type="bullet">
+/// <item><description><c>_routersBySource</c> — For each source executor, a list of <see cref="IDurableEdgeRouter"/> instances
+/// that know how to deliver messages to successor executors. When a source has multiple successors, a single
+/// <see cref="DurableFanOutEdgeRouter"/> wraps the individual <see cref="DurableDirectEdgeRouter"/> instances.</description></item>
+/// <item><description><c>_predecessorCounts</c> — The number of predecessors for each executor, used to detect
+/// fan-in points where multiple incoming messages should be aggregated before execution.</description></item>
+/// <item><description><c>_startExecutorId</c> — The entry-point executor that receives the initial workflow input.</description></item>
+/// </list>
+/// <para>
+/// <b>How it is used during execution:</b>
+/// </para>
+/// <list type="number">
+/// <item><description><see cref="EnqueueInitialInput"/> seeds the start executor's queue before the first superstep.</description></item>
+/// <item><description>After each superstep, <c>DurableWorkflowRunner.RouteOutputToSuccessors</c> calls
+/// <see cref="RouteMessage"/> which looks up the routers for the completed executor and forwards the
+/// result to successor queues. Each router may evaluate an edge condition before enqueueing.</description></item>
+/// <item><description><see cref="IsFanInExecutor"/> is checked during input collection to decide whether
+/// to aggregate multiple queued messages into a single JSON array before dispatching.</description></item>
+/// </list>
+/// </remarks>
+internal sealed class DurableEdgeMap
+{
+    private readonly Dictionary<string, List<IDurableEdgeRouter>> _routersBySource = [];
+    private readonly Dictionary<string, int> _predecessorCounts = [];
+    private readonly string _startExecutorId;
+
+    /// <summary>
+    /// Initializes a new instance of <see cref="DurableEdgeMap"/> from workflow graph info.
+    /// </summary>
+    /// <param name="graphInfo">The workflow graph information containing routing structure.</param>
+    internal DurableEdgeMap(WorkflowGraphInfo graphInfo)
+    {
+        ArgumentNullException.ThrowIfNull(graphInfo);
+
+        this._startExecutorId = graphInfo.StartExecutorId;
+
+        // Build edge routers for each source executor
+        foreach (KeyValuePair<string, List<string>> entry in graphInfo.Successors)
+        {
+            string sourceId = entry.Key;
+            List<string> successorIds = entry.Value;
+
+            if (successorIds.Count == 0)
+            {
+                continue;
+            }
+
+            graphInfo.ExecutorOutputTypes.TryGetValue(sourceId, out Type? sourceOutputType);
+
+            List<IDurableEdgeRouter> routers = [];
+            foreach (string sinkId in successorIds)
+            {
+                graphInfo.EdgeConditions.TryGetValue((sourceId, sinkId), out Func<object?, bool>? condition);
+
+                routers.Add(new DurableDirectEdgeRouter(sourceId, sinkId, condition, sourceOutputType));
+            }
+
+            // If multiple successors, wrap in a fan-out router
+            if (routers.Count > 1)
+            {
+                this._routersBySource[sourceId] = [new DurableFanOutEdgeRouter(sourceId, routers)];
+            }
+            else
+            {
+                this._routersBySource[sourceId] = routers;
+            }
+        }
+
+        // Store predecessor counts for fan-in detection
+        foreach (KeyValuePair<string, List<string>> entry in graphInfo.Predecessors)
+        {
+            this._predecessorCounts[entry.Key] = entry.Value.Count;
+        }
+    }
+
+    /// <summary>
+    /// Routes a message from a source executor to its successors.
+    /// </summary>
+    /// <remarks>
+    /// Called by <c>DurableWorkflowRunner.RouteOutputToSuccessors</c> after each superstep.
+    /// Wraps the message in a <see cref="DurableMessageEnvelope"/> and delegates to the
+    /// appropriate <see cref="IDurableEdgeRouter"/>(s) for the source executor. Each router
+    /// may evaluate an edge condition and, if satisfied, enqueue the envelope into the
+    /// target executor's message queue for the next superstep.
+    /// </remarks>
+    /// <param name="sourceId">The source executor ID.</param>
+    /// <param name="message">The serialized message to route.</param>
+    /// <param name="inputTypeName">The type name of the message.</param>
+    /// <param name="messageQueues">The message queues to enqueue messages into.</param>
+    /// <param name="logger">The logger for tracing.</param>
+    internal void RouteMessage(
+        string sourceId,
+        string message,
+        string? inputTypeName,
+        Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues,
+        ILogger logger)
+    {
+        if (!this._routersBySource.TryGetValue(sourceId, out List<IDurableEdgeRouter>? routers))
+        {
+            return;
+        }
+
+        DurableMessageEnvelope envelope = DurableMessageEnvelope.Create(message, inputTypeName, sourceId);
+
+        foreach (IDurableEdgeRouter router in routers)
+        {
+            router.RouteMessage(envelope, messageQueues, logger);
+        }
+    }
+
+    /// <summary>
+    /// Enqueues the initial workflow input to the start executor.
+    /// </summary>
+    /// <param name="message">The serialized initial input message.</param>
+    /// <param name="messageQueues">The message queues to enqueue into.</param>
+    /// <remarks>
+    /// This method is used only at workflow startup to provide input to the first executor.
+    /// No input type hint is required because the start executor determines its expected input type from its own <c>InputTypes</c> configuration.
+    /// </remarks>
+    internal void EnqueueInitialInput(
+        string message,
+        Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues)
+    {
+        DurableMessageEnvelope envelope = DurableMessageEnvelope.Create(message, inputTypeName: null);
+        EnqueueMessage(messageQueues, this._startExecutorId, envelope);
+    }
+
+    /// <summary>
+    /// Determines if an executor is a fan-in point (has multiple predecessors).
+    /// </summary>
+    /// <param name="executorId">The executor ID to check.</param>
+    /// <returns><c>true</c> if the executor has multiple predecessors; otherwise, <c>false</c>.</returns>
+    internal bool IsFanInExecutor(string executorId)
+    {
+        return this._predecessorCounts.TryGetValue(executorId, out int count) && count > 1;
+    }
+
+    private static void EnqueueMessage(
+        Dictionary<string, Queue<DurableMessageEnvelope>> queues,
+        string executorId,
+        DurableMessageEnvelope envelope)
+    {
+        if (!queues.TryGetValue(executorId, out Queue<DurableMessageEnvelope>? queue))
+        {
+            queue = new Queue<DurableMessageEnvelope>();
+            queues[executorId] = queue;
+        }
+
+        queue.Enqueue(envelope);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/EdgeRouters/DurableFanOutEdgeRouter.cs

@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Fan-out routing: one source message is forwarded to multiple targets.
+// Example from a workflow like below:
+//
+//     [A] ──► [B] ──► [C] ──► [E]          (B→D has condition: x => x.NeedsReview)
+//              │               ▲
+//              └──► [D] ──────┘
+//
+//  B has two successors (C and D), so DurableEdgeMap wraps them:
+//
+//     Executor B completes with resultB (type: Order)
+//       │
+//       ▼
+//     FanOutRouter(B)
+//       ├──► DirectRouter(B→C) ──► no condition       ──► enqueue to C
+//       └──► DirectRouter(B→D) ──► x => x.NeedsReview ──► enqueue to D (or skip)
+//
+//  Each DirectRouter independently evaluates its condition,
+//  so resultB always reaches C, but only reaches D if NeedsReview is true.
+
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows.EdgeRouters;
+
+/// <summary>
+/// Routes messages from a source executor to multiple target executors (fan-out pattern).
+/// </summary>
+/// <remarks>
+/// Created by <see cref="DurableEdgeMap"/> when a source executor has more than one successor.
+/// Wraps the individual <see cref="DurableDirectEdgeRouter"/> instances and delegates
+/// <see cref="RouteMessage"/> to each of them, so the same message is evaluated and
+/// potentially enqueued for every target independently.
+/// </remarks>
+internal sealed class DurableFanOutEdgeRouter : IDurableEdgeRouter
+{
+    private readonly string _sourceId;
+    private readonly List<IDurableEdgeRouter> _targetRouters;
+
+    /// <summary>
+    /// Initializes a new instance of <see cref="DurableFanOutEdgeRouter"/>.
+    /// </summary>
+    /// <param name="sourceId">The source executor ID.</param>
+    /// <param name="targetRouters">The routers for each target executor.</param>
+    internal DurableFanOutEdgeRouter(string sourceId, List<IDurableEdgeRouter> targetRouters)
+    {
+        this._sourceId = sourceId;
+        this._targetRouters = targetRouters;
+    }
+
+    /// <inheritdoc />
+    public void RouteMessage(
+        DurableMessageEnvelope envelope,
+        Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues,
+        ILogger logger)
+    {
+        if (logger.IsEnabled(LogLevel.Debug))
+        {
+            logger.LogDebug("Fan-Out from {Source}: routing to {Count} targets", this._sourceId, this._targetRouters.Count);
+        }
+
+        foreach (IDurableEdgeRouter targetRouter in this._targetRouters)
+        {
+            targetRouter.RouteMessage(envelope, messageQueues, logger);
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/EdgeRouters/IDurableEdgeRouter.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.Logging;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows.EdgeRouters;
+
+/// <summary>
+/// Defines the contract for routing messages through workflow edges in durable orchestrations.
+/// </summary>
+/// <remarks>
+/// Implementations include <see cref="DurableDirectEdgeRouter"/> for single-target routing
+/// and <see cref="DurableFanOutEdgeRouter"/> for multi-target fan-out patterns.
+/// </remarks>
+internal interface IDurableEdgeRouter
+{
+    /// <summary>
+    /// Routes a message from the source executor to its target(s).
+    /// </summary>
+    /// <param name="envelope">The message envelope containing the message and metadata.</param>
+    /// <param name="messageQueues">The message queues to enqueue messages into.</param>
+    /// <param name="logger">The logger for tracing.</param>
+    void RouteMessage(
+        DurableMessageEnvelope envelope,
+        Dictionary<string, Queue<DurableMessageEnvelope>> messageQueues,
+        ILogger logger);
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/ExecutorRegistry.cs

@@ -0,0 +1,83 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Provides a registry for executor bindings used in durable workflow orchestrations.
+/// </summary>
+/// <remarks>
+/// This registry enables lookup of executors by name, decoupled from specific workflow instances.
+/// Executors are registered when workflows are added to <see cref="DurableWorkflowOptions"/>.
+/// </remarks>
+internal sealed class ExecutorRegistry
+{
+    private readonly Dictionary<string, ExecutorRegistration> _executors = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <summary>
+    /// Gets the number of registered executors.
+    /// </summary>
+    internal int Count => this._executors.Count;
+
+    /// <summary>
+    /// Attempts to get an executor registration by name.
+    /// </summary>
+    /// <param name="executorName">The executor name to look up.</param>
+    /// <param name="registration">When this method returns, contains the registration if found; otherwise, null.</param>
+    /// <returns><see langword="true"/> if the executor was found; otherwise, <see langword="false"/>.</returns>
+    internal bool TryGetExecutor(string executorName, [NotNullWhen(true)] out ExecutorRegistration? registration)
+    {
+        return this._executors.TryGetValue(executorName, out registration);
+    }
+
+    /// <summary>
+    /// Registers an executor binding from a workflow.
+    /// </summary>
+    /// <param name="executorName">The executor name (without GUID suffix).</param>
+    /// <param name="executorId">The full executor ID (may include GUID suffix).</param>
+    /// <param name="workflow">The workflow containing the executor.</param>
+    internal void Register(string executorName, string executorId, Workflow workflow)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(executorName);
+        ArgumentException.ThrowIfNullOrEmpty(executorId);
+        ArgumentNullException.ThrowIfNull(workflow);
+
+        Dictionary<string, ExecutorBinding> bindings = workflow.ReflectExecutors();
+        if (!bindings.TryGetValue(executorId, out ExecutorBinding? binding))
+        {
+            throw new InvalidOperationException($"Executor '{executorId}' not found in workflow.");
+        }
+
+        this._executors.TryAdd(executorName, new ExecutorRegistration(executorId, binding));
+    }
+}
+
+/// <summary>
+/// Represents a registered executor with its binding information.
+/// </summary>
+/// <remarks>
+/// The <paramref name="ExecutorId"/> may differ from the registered name when the executor
+/// ID includes an instance suffix (e.g., "ExecutorName_Guid").
+/// </remarks>
+/// <param name="ExecutorId">The full executor ID (may include instance suffix).</param>
+/// <param name="Binding">The executor binding containing the factory and configuration.</param>
+internal sealed record ExecutorRegistration(string ExecutorId, ExecutorBinding Binding)
+{
+    /// <summary>
+    /// Creates an instance of the executor.
+    /// </summary>
+    /// <param name="runId">A unique identifier for the run context.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The created executor instance.</returns>
+    internal async ValueTask<Executor> CreateExecutorInstanceAsync(string runId, CancellationToken cancellationToken = default)
+    {
+        if (this.Binding.FactoryAsync is null)
+        {
+            throw new InvalidOperationException($"Cannot create executor '{this.ExecutorId}': Binding is a placeholder.");
+        }
+
+        return await this.Binding.FactoryAsync(runId).ConfigureAwait(false);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/IAwaitableWorkflowRun.cs

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Represents a workflow run that can be awaited for completion.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This interface extends <see cref="IWorkflowRun"/> to provide methods for waiting
+/// until the workflow execution completes. Not all workflow runners support this capability.
+/// </para>
+/// <para>
+/// Use pattern matching to check if a workflow run supports awaiting:
+/// <code>
+/// IWorkflowRun run = await client.RunAsync(workflow, input);
+/// if (run is IAwaitableWorkflowRun awaitableRun)
+/// {
+///     string? result = await awaitableRun.WaitForCompletionAsync&lt;string&gt;();
+/// }
+/// </code>
+/// </para>
+/// </remarks>
+public interface IAwaitableWorkflowRun : IWorkflowRun
+{
+    /// <summary>
+    /// Waits for the workflow to complete and returns the result.
+    /// </summary>
+    /// <typeparam name="TResult">The expected result type.</typeparam>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>The result of the workflow execution.</returns>
+    /// <exception cref="InvalidOperationException">Thrown when the workflow failed or was terminated.</exception>
+    ValueTask<TResult?> WaitForCompletionAsync<TResult>(CancellationToken cancellationToken = default);
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/IStreamingWorkflowRun.cs

@@ -0,0 +1,55 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Represents a workflow run that supports streaming workflow events as they occur.
+/// </summary>
+/// <remarks>
+/// This interface defines the contract for streaming workflow runs in durable execution
+/// environments. Implementations provide real-time access to workflow events.
+/// </remarks>
+public interface IStreamingWorkflowRun
+{
+    /// <summary>
+    /// Gets the unique identifier for the run.
+    /// </summary>
+    /// <remarks>
+    /// This identifier can be provided at the start of the run, or auto-generated.
+    /// For durable runs, this corresponds to the orchestration instance ID.
+    /// </remarks>
+    string RunId { get; }
+
+    /// <summary>
+    /// Asynchronously streams workflow events as they occur during workflow execution.
+    /// </summary>
+    /// <remarks>
+    /// This method yields <see cref="WorkflowEvent"/> instances in real time as the workflow
+    /// progresses. The stream completes when the workflow completes, fails, or is terminated.
+    /// Events are delivered in the order they are raised.
+    /// </remarks>
+    /// <param name="cancellationToken">
+    /// A <see cref="CancellationToken"/> that can be used to cancel the streaming operation.
+    /// If cancellation is requested, the stream will end and no further events will be yielded.
+    /// </param>
+    /// <returns>
+    /// An asynchronous stream of <see cref="WorkflowEvent"/> objects representing significant
+    /// workflow state changes.
+    /// </returns>
+    IAsyncEnumerable<WorkflowEvent> WatchStreamAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Sends a response to a <see cref="DurableWorkflowWaitingForInputEvent"/> to resume the workflow.
+    /// </summary>
+    /// <typeparam name="TResponse">The type of the response data.</typeparam>
+    /// <param name="requestEvent">The request event to respond to.</param>
+    /// <param name="response">The response data to send.</param>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
+    ValueTask SendResponseAsync<TResponse>(
+        DurableWorkflowWaitingForInputEvent requestEvent,
+        TResponse response,
+        CancellationToken cancellationToken = default);
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/IWorkflowClient.cs

@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Defines a client for running and managing workflow executions.
+/// </summary>
+public interface IWorkflowClient
+{
+    /// <summary>
+    /// Runs a workflow and returns a handle to monitor its execution.
+    /// </summary>
+    /// <typeparam name="TInput">The type of the input to the workflow.</typeparam>
+    /// <param name="workflow">The workflow to execute.</param>
+    /// <param name="input">The input to pass to the workflow's starting executor.</param>
+    /// <param name="runId">Optional identifier for the run. If not provided, a new ID will be generated.</param>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>An <see cref="IWorkflowRun"/> that can be used to monitor the workflow execution.</returns>
+    ValueTask<IWorkflowRun> RunAsync<TInput>(
+        Workflow workflow,
+        TInput input,
+        string? runId = null,
+        CancellationToken cancellationToken = default)
+        where TInput : notnull;
+
+    /// <summary>
+    /// Runs a workflow with string input and returns a handle to monitor its execution.
+    /// </summary>
+    /// <param name="workflow">The workflow to execute.</param>
+    /// <param name="input">The string input to pass to the workflow.</param>
+    /// <param name="runId">Optional identifier for the run. If not provided, a new ID will be generated.</param>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>An <see cref="IWorkflowRun"/> that can be used to monitor the workflow execution.</returns>
+    ValueTask<IWorkflowRun> RunAsync(
+        Workflow workflow,
+        string input,
+        string? runId = null,
+        CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Starts a workflow and returns a streaming handle to watch events in real-time.
+    /// </summary>
+    /// <typeparam name="TInput">The type of the input to the workflow.</typeparam>
+    /// <param name="workflow">The workflow to execute.</param>
+    /// <param name="input">The input to pass to the workflow's starting executor.</param>
+    /// <param name="runId">Optional identifier for the run. If not provided, a new ID will be generated.</param>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>An <see cref="IStreamingWorkflowRun"/> that can be used to stream workflow events.</returns>
+    ValueTask<IStreamingWorkflowRun> StreamAsync<TInput>(
+        Workflow workflow,
+        TInput input,
+        string? runId = null,
+        CancellationToken cancellationToken = default)
+        where TInput : notnull;
+
+    /// <summary>
+    /// Starts a workflow with string input and returns a streaming handle to watch events in real-time.
+    /// </summary>
+    /// <param name="workflow">The workflow to execute.</param>
+    /// <param name="input">The string input to pass to the workflow.</param>
+    /// <param name="runId">Optional identifier for the run. If not provided, a new ID will be generated.</param>
+    /// <param name="cancellationToken">A cancellation token to observe.</param>
+    /// <returns>An <see cref="IStreamingWorkflowRun"/> that can be used to stream workflow events.</returns>
+    ValueTask<IStreamingWorkflowRun> StreamAsync(
+        Workflow workflow,
+        string input,
+        string? runId = null,
+        CancellationToken cancellationToken = default);
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/IWorkflowRun.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Represents a running instance of a workflow.
+/// </summary>
+public interface IWorkflowRun
+{
+    /// <summary>
+    /// Gets the unique identifier for the run.
+    /// </summary>
+    /// <remarks>
+    /// This identifier can be provided at the start of the run, or auto-generated.
+    /// For durable runs, this corresponds to the orchestration instance ID.
+    /// </remarks>
+    string RunId { get; }
+
+    /// <summary>
+    /// Gets all events that have been emitted by the workflow.
+    /// </summary>
+    IEnumerable<WorkflowEvent> OutgoingEvents { get; }
+
+    /// <summary>
+    /// Gets the number of events emitted since the last access to <see cref="NewEvents"/>.
+    /// </summary>
+    int NewEventCount { get; }
+
+    /// <summary>
+    /// Gets all events emitted by the workflow since the last access to this property.
+    /// </summary>
+    /// <remarks>
+    /// Each access to this property advances the bookmark, so subsequent accesses
+    /// will only return events emitted after the previous access.
+    /// </remarks>
+    IEnumerable<WorkflowEvent> NewEvents { get; }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/PendingRequestPortStatus.cs

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Represents a RequestPort the workflow is paused at, waiting for a response.
+/// </summary>
+/// <param name="EventName">The RequestPort ID identifying which input is needed.</param>
+/// <param name="Input">The serialized request data passed to the RequestPort.</param>
+internal sealed record PendingRequestPortStatus(
+    string EventName,
+    string Input);

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/TypedPayload.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Pairs a JSON-serialized payload with its assembly-qualified type name
+/// for type-safe deserialization across activity boundaries.
+/// </summary>
+internal sealed class TypedPayload
+{
+    /// <summary>
+    /// Gets or sets the assembly-qualified type name of the payload.
+    /// </summary>
+    public string? TypeName { get; set; }
+
+    /// <summary>
+    /// Gets or sets the serialized payload data as JSON.
+    /// </summary>
+    public string? Data { get; set; }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/WorkflowAnalyzer.cs

@@ -0,0 +1,245 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Analyzes workflow structure to extract executor metadata and build graph information
+/// for message-driven execution.
+/// </summary>
+internal static class WorkflowAnalyzer
+{
+    private const string AgentExecutorTypeName = "AIAgentHostExecutor";
+    private const string AgentAssemblyPrefix = "Microsoft.Agents.AI";
+    private const string ExecutorTypePrefix = "Executor";
+
+    /// <summary>
+    /// Analyzes a workflow instance and returns a list of executors with their metadata.
+    /// </summary>
+    /// <param name="workflow">The workflow instance to analyze.</param>
+    /// <returns>A list of executor information in workflow order.</returns>
+    internal static List<WorkflowExecutorInfo> GetExecutorsFromWorkflowInOrder(Workflow workflow)
+    {
+        ArgumentNullException.ThrowIfNull(workflow);
+
+        return workflow.ReflectExecutors()
+            .Select(kvp => CreateExecutorInfo(kvp.Key, kvp.Value))
+            .ToList();
+    }
+
+    /// <summary>
+    /// Builds the workflow graph information needed for message-driven execution.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Extracts routing information including successors, predecessors, edge conditions,
+    /// and output types. Supports cyclic workflows through message-driven superstep execution.
+    /// </para>
+    /// <para>
+    /// The returned <see cref="WorkflowGraphInfo"/> is consumed by <c>DurableEdgeMap</c>
+    /// to build the runtime routing layer:
+    /// <c>Successors</c> become <c>IDurableEdgeRouter</c> instances,
+    /// <c>Predecessors</c> become fan-in counts, and
+    /// <c>EdgeConditions</c> / <c>ExecutorOutputTypes</c> are passed into
+    /// <c>DurableDirectEdgeRouter</c> for conditional routing with typed deserialization.
+    /// </para>
+    /// </remarks>
+    /// <param name="workflow">The workflow instance to analyze.</param>
+    /// <returns>A graph info object containing routing information.</returns>
+    internal static WorkflowGraphInfo BuildGraphInfo(Workflow workflow)
+    {
+        ArgumentNullException.ThrowIfNull(workflow);
+
+        Dictionary<string, ExecutorBinding> executors = workflow.ReflectExecutors();
+
+        WorkflowGraphInfo graphInfo = new()
+        {
+            StartExecutorId = workflow.StartExecutorId
+        };
+
+        InitializeExecutorMappings(graphInfo, executors);
+        PopulateGraphFromEdges(graphInfo, workflow.Edges);
+
+        return graphInfo;
+    }
+
+    /// <summary>
+    /// Determines whether the specified executor type is an agentic executor.
+    /// </summary>
+    /// <param name="executorType">The executor type to check.</param>
+    /// <returns><c>true</c> if the executor is an agentic executor; otherwise, <c>false</c>.</returns>
+    internal static bool IsAgentExecutorType(Type executorType)
+    {
+        string typeName = executorType.FullName ?? executorType.Name;
+        string assemblyName = executorType.Assembly.GetName().Name ?? string.Empty;
+
+        return typeName.Contains(AgentExecutorTypeName, StringComparison.OrdinalIgnoreCase)
+            && assemblyName.Contains(AgentAssemblyPrefix, StringComparison.OrdinalIgnoreCase);
+    }
+
+    /// <summary>
+    /// Creates a <see cref="WorkflowExecutorInfo"/> from an executor binding.
+    /// </summary>
+    /// <param name="executorId">The unique identifier of the executor.</param>
+    /// <param name="binding">The executor binding containing type and configuration information.</param>
+    /// <returns>A new <see cref="WorkflowExecutorInfo"/> instance with extracted metadata.</returns>
+    private static WorkflowExecutorInfo CreateExecutorInfo(string executorId, ExecutorBinding binding)
+    {
+        bool isAgentic = IsAgentExecutorType(binding.ExecutorType);
+        RequestPort? requestPort = (binding is RequestPortBinding rpb) ? rpb.Port : null;
+        Workflow? subWorkflow = (binding is SubworkflowBinding swb) ? swb.WorkflowInstance : null;
+
+        return new WorkflowExecutorInfo(executorId, isAgentic, requestPort, subWorkflow);
+    }
+
+    /// <summary>
+    /// Initializes the graph info with empty collections for each executor.
+    /// </summary>
+    /// <param name="graphInfo">The graph info to initialize.</param>
+    /// <param name="executors">The dictionary of executor bindings.</param>
+    private static void InitializeExecutorMappings(WorkflowGraphInfo graphInfo, Dictionary<string, ExecutorBinding> executors)
+    {
+        foreach ((string executorId, ExecutorBinding binding) in executors)
+        {
+            graphInfo.Successors[executorId] = [];
+            graphInfo.Predecessors[executorId] = [];
+            graphInfo.ExecutorOutputTypes[executorId] = GetExecutorOutputType(binding.ExecutorType);
+        }
+    }
+
+    /// <summary>
+    /// Populates the graph info with successor/predecessor relationships and edge conditions.
+    /// </summary>
+    /// <param name="graphInfo">The graph info to populate.</param>
+    /// <param name="edges">The dictionary of edges grouped by source executor ID.</param>
+    private static void PopulateGraphFromEdges(WorkflowGraphInfo graphInfo, Dictionary<string, HashSet<Edge>> edges)
+    {
+        foreach ((string sourceId, HashSet<Edge> edgeSet) in edges)
+        {
+            List<string> successors = graphInfo.Successors[sourceId];
+
+            foreach (Edge edge in edgeSet)
+            {
+                AddSuccessorsFromEdge(graphInfo, sourceId, edge, successors);
+                TryAddEdgeCondition(graphInfo, edge);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Adds successor relationships from an edge to the graph info.
+    /// </summary>
+    /// <param name="graphInfo">The graph info to update.</param>
+    /// <param name="sourceId">The source executor ID.</param>
+    /// <param name="edge">The edge containing connection information.</param>
+    /// <param name="successors">The list of successors to append to.</param>
+    private static void AddSuccessorsFromEdge(
+        WorkflowGraphInfo graphInfo,
+        string sourceId,
+        Edge edge,
+        List<string> successors)
+    {
+        foreach (string sinkId in edge.Data.Connection.SinkIds)
+        {
+            if (!graphInfo.Successors.ContainsKey(sinkId))
+            {
+                continue;
+            }
+
+            successors.Add(sinkId);
+            graphInfo.Predecessors[sinkId].Add(sourceId);
+        }
+    }
+
+    /// <summary>
+    /// Extracts and adds an edge condition to the graph info if present.
+    /// </summary>
+    /// <param name="graphInfo">The graph info to update.</param>
+    /// <param name="edge">The edge that may contain a condition.</param>
+    private static void TryAddEdgeCondition(WorkflowGraphInfo graphInfo, Edge edge)
+    {
+        DirectEdgeData? directEdge = edge.DirectEdgeData;
+
+        if (directEdge?.Condition is not null)
+        {
+            graphInfo.EdgeConditions[(directEdge.SourceId, directEdge.SinkId)] = directEdge.Condition;
+        }
+    }
+
+    /// <summary>
+    /// Extracts the output type from an executor type by walking the inheritance chain.
+    /// </summary>
+    /// <param name="executorType">The executor type to analyze.</param>
+    /// <returns>
+    /// The TOutput type for Executor&lt;TInput, TOutput&gt;,
+    /// or <c>null</c> for Executor&lt;TInput&gt; (void output) or non-executor types.
+    /// </returns>
+    private static Type? GetExecutorOutputType(Type executorType)
+    {
+        Type? currentType = executorType;
+
+        while (currentType is not null)
+        {
+            Type? outputType = TryExtractOutputTypeFromGeneric(currentType);
+            if (outputType is not null || IsVoidExecutorType(currentType))
+            {
+                return outputType;
+            }
+
+            currentType = currentType.BaseType;
+        }
+
+        return null;
+    }
+
+    /// <summary>
+    /// Attempts to extract the output type from a generic executor type.
+    /// </summary>
+    /// <param name="type">The type to inspect.</param>
+    /// <returns>The TOutput type if this is an Executor&lt;TInput, TOutput&gt;; otherwise, <c>null</c>.</returns>
+    private static Type? TryExtractOutputTypeFromGeneric(Type type)
+    {
+        if (!type.IsGenericType)
+        {
+            return null;
+        }
+
+        Type genericDefinition = type.GetGenericTypeDefinition();
+        Type[] genericArgs = type.GetGenericArguments();
+
+        bool isExecutorType = genericDefinition.Name.StartsWith(ExecutorTypePrefix, StringComparison.Ordinal);
+        if (!isExecutorType)
+        {
+            return null;
+        }
+
+        // Executor<TInput, TOutput> - return TOutput
+        if (genericArgs.Length == 2)
+        {
+            return genericArgs[1];
+        }
+
+        return null;
+    }
+
+    /// <summary>
+    /// Determines whether the type is a void-returning executor (Executor&lt;TInput&gt;).
+    /// </summary>
+    /// <param name="type">The type to check.</param>
+    /// <returns><c>true</c> if this is an Executor with a single type parameter; otherwise, <c>false</c>.</returns>
+    private static bool IsVoidExecutorType(Type type)
+    {
+        if (!type.IsGenericType)
+        {
+            return false;
+        }
+
+        Type genericDefinition = type.GetGenericTypeDefinition();
+        Type[] genericArgs = type.GetGenericArguments();
+
+        // Executor<TInput> with 1 type parameter indicates void return
+        return genericArgs.Length == 1
+            && genericDefinition.Name.StartsWith(ExecutorTypePrefix, StringComparison.Ordinal);
+    }
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/WorkflowExecutorInfo.cs

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Represents an executor in the workflow with its metadata.
+/// </summary>
+/// <param name="ExecutorId">The unique identifier of the executor.</param>
+/// <param name="IsAgenticExecutor">Indicates whether this executor is an agentic executor.</param>
+/// <param name="RequestPort">The request port if this executor is a request port executor; otherwise, null.</param>
+/// <param name="SubWorkflow">The sub-workflow if this executor is a sub-workflow executor; otherwise, null.</param>
+internal sealed record WorkflowExecutorInfo(
+    string ExecutorId,
+    bool IsAgenticExecutor,
+    RequestPort? RequestPort = null,
+    Workflow? SubWorkflow = null)
+{
+    /// <summary>
+    /// Gets a value indicating whether this executor is a request port executor (human-in-the-loop).
+    /// </summary>
+    public bool IsRequestPortExecutor => this.RequestPort is not null;
+
+    /// <summary>
+    /// Gets a value indicating whether this executor is a sub-workflow executor.
+    /// </summary>
+    public bool IsSubworkflowExecutor => this.SubWorkflow is not null;
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/WorkflowGraphInfo.cs

@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// Example: Given this workflow graph with a fan-out from B and a fan-in at E,
+// plus a conditional edge from B to D:
+//
+//     [A] ──► [B] ──► [C] ──► [E]
+//              │               ▲
+//              └──► [D] ──────┘
+//                (condition:
+//                 x => x.NeedsReview)
+//
+// WorkflowAnalyzer.BuildGraphInfo() produces:
+//
+//  StartExecutorId = "A"
+//
+//  Successors (who does each executor send output to?):
+//  ┌──────────┬──────────────┐
+//  │ "A"      │ ["B"]        │
+//  │ "B"      │ ["C", "D"]   │  ◄── fan-out: B sends to both C and D
+//  │ "C"      │ ["E"]        │
+//  │ "D"      │ ["E"]        │
+//  │ "E"      │ []           │  ◄── terminal: no successors
+//  └──────────┴──────────────┘
+//
+//  Predecessors (who feeds into each executor?):
+//  ┌──────────┬──────────────┐
+//  │ "A"      │ []           │  ◄── start: no predecessors
+//  │ "B"      │ ["A"]        │
+//  │ "C"      │ ["B"]        │
+//  │ "D"      │ ["B"]        │
+//  │ "E"      │ ["C", "D"]   │  ◄── fan-in: count=2, messages will be aggregated
+//  └──────────┴──────────────┘
+//
+//  EdgeConditions (which edges have routing conditions?):
+//  ┌──────────────────┬──────────────────────────┐
+//  │ ("B", "D")       │ x => x.NeedsReview       │  ◄── D only receives if condition is true
+//  └──────────────────┴──────────────────────────┘
+//  (The B→C edge has no condition, so C always receives B's output.)
+//
+//  ExecutorOutputTypes (what type does each executor return?):
+//  ┌──────────┬──────────────────┐
+//  │ "A"      │ typeof(string)   │  ◄── used by DurableDirectEdgeRouter to deserialize
+//  │ "B"      │ typeof(Order)    │      the JSON message for condition evaluation
+//  │ "C"      │ typeof(Report)   │
+//  │ "D"      │ typeof(Report)   │
+//  │ "E"      │ typeof(string)   │
+//  └──────────┴──────────────────┘
+//
+// DurableEdgeMap then consumes this to build the runtime routing layer.
+
+using System.Diagnostics;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Represents the workflow graph structure needed for message-driven execution.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This is a simplified representation that contains only the information needed
+/// for routing messages between executors during superstep execution:
+/// </para>
+/// <list type="bullet">
+/// <item><description>Successors for routing messages forward</description></item>
+/// <item><description>Predecessors for detecting fan-in points</description></item>
+/// <item><description>Edge conditions for conditional routing</description></item>
+/// <item><description>Output types for deserialization during condition evaluation</description></item>
+/// </list>
+/// </remarks>
+[DebuggerDisplay("Start = {StartExecutorId}, Executors = {Successors.Count}")]
+internal sealed class WorkflowGraphInfo
+{
+    /// <summary>
+    /// Gets or sets the starting executor ID for the workflow.
+    /// </summary>
+    public string StartExecutorId { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Maps each executor ID to its successors (for message routing).
+    /// </summary>
+    public Dictionary<string, List<string>> Successors { get; } = [];
+
+    /// <summary>
+    /// Maps each executor ID to its predecessors (for fan-in detection).
+    /// </summary>
+    public Dictionary<string, List<string>> Predecessors { get; } = [];
+
+    /// <summary>
+    /// Maps edge connections (sourceId, targetId) to their condition functions.
+    /// The condition function takes the predecessor's result and returns true if the edge should be followed.
+    /// </summary>
+    public Dictionary<(string SourceId, string TargetId), Func<object?, bool>?> EdgeConditions { get; } = [];
+
+    /// <summary>
+    /// Maps executor IDs to their output types (for proper deserialization during condition evaluation).
+    /// </summary>
+    public Dictionary<string, Type?> ExecutorOutputTypes { get; } = [];
+}

dotnet/src/Microsoft.Agents.AI.DurableTask/Workflows/WorkflowNamingHelper.cs

@@ -0,0 +1,113 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.Agents.AI.DurableTask.Workflows;
+
+/// <summary>
+/// Provides helper methods for workflow naming conventions used in durable orchestrations.
+/// </summary>
+internal static class WorkflowNamingHelper
+{
+    internal const string OrchestrationFunctionPrefix = "dafx-";
+    private const char ExecutorIdSuffixSeparator = '_';
+
+    /// <summary>
+    /// Converts a workflow name to its corresponding orchestration function name.
+    /// </summary>
+    /// <param name="workflowName">The workflow name.</param>
+    /// <returns>The orchestration function name.</returns>
+    /// <exception cref="ArgumentException">Thrown when the workflow name is null or empty.</exception>
+    internal static string ToOrchestrationFunctionName(string workflowName)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(workflowName);
+        return string.Concat(OrchestrationFunctionPrefix, workflowName);
+    }
+
+    /// <summary>
+    /// Converts an orchestration function name back to its workflow name.
+    /// </summary>
+    /// <param name="orchestrationFunctionName">The orchestration function name.</param>
+    /// <returns>The workflow name.</returns>
+    /// <exception cref="ArgumentException">Thrown when the orchestration function name is null, empty, or doesn't have the expected prefix.</exception>
+    internal static string ToWorkflowName(string orchestrationFunctionName)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(orchestrationFunctionName);
+
+        if (!TryGetWorkflowName(orchestrationFunctionName, out string? workflowName))
+        {
+            throw new ArgumentException(
+                $"Orchestration function name '{orchestrationFunctionName}' does not have the expected '{OrchestrationFunctionPrefix}' prefix or is missing a workflow name.",
+                nameof(orchestrationFunctionName));
+        }
+
+        return workflowName;
+    }
+
+    /// <summary>
+    /// Extracts the executor name from an executor ID.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// For non-agentic executors, the executor ID is the same as the executor name (e.g., "OrderParser").
+    /// </para>
+    /// <para>
+    /// For agentic executors, the workflow builder appends a GUID suffix separated by an underscore
+    /// (e.g., "Physicist_8884e71021334ce49517fa2b17b1695b"). This method extracts just the name portion.
+    /// </para>
+    /// </remarks>
+    /// <param name="executorId">The executor ID, which may contain a GUID suffix.</param>
+    /// <returns>The executor name without any GUID suffix.</returns>
+    /// <exception cref="ArgumentException">Thrown when the executor ID is null or empty.</exception>
+    internal static string GetExecutorName(string executorId)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(executorId);
+
+        int separatorIndex = executorId.LastIndexOf(ExecutorIdSuffixSeparator);
+        if (separatorIndex > 0)
+        {
+            ReadOnlySpan<char> suffix = executorId.AsSpan(separatorIndex + 1);
+            if (IsGuidSuffix(suffix))
+            {
+                return executorId[..separatorIndex];
+            }
+        }
+
+        return executorId;
+    }
+
+    /// <summary>
+    /// Checks whether the given span looks like a sanitized GUID (32 hex characters).
+    /// </summary>
+    private static bool IsGuidSuffix(ReadOnlySpan<char> value)
+    {
+        if (value.Length != 32)
+        {
+            return false;
+        }
+
+        foreach (char c in value)
+        {
+            if (!char.IsAsciiHexDigit(c))
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    private static bool TryGetWorkflowName(string? orchestrationFunctionName, [NotNullWhen(true)] out string? workflowName)
+    {
+        workflowName = null;
+
+        if (string.IsNullOrEmpty(orchestrationFunctionName) ||
+            !orchestrationFunctionName.StartsWith(OrchestrationFunctionPrefix, StringComparison.Ordinal))
+        {
+            return false;
+        }
+
+        workflowName = orchestrationFunctionName[OrchestrationFunctionPrefix.Length..];
+        return workflowName.Length > 0;
+    }
+}