Skip to content

.NET: Map workflow lifecycle to AG-UI - #7738

Draft
Javier Calvarro Nelson (javiercn) wants to merge 17 commits into
mainfrom
javiercn-workflow-ag-ui-events
Draft

.NET: Map workflow lifecycle to AG-UI#7738
Javier Calvarro Nelson (javiercn) wants to merge 17 commits into
mainfrom
javiercn-workflow-ag-ui-events

Conversation

@javiercn

@javiercnJavier Calvarro Nelson (javiercn) commented Aug 18, 2026•
edited
Loading

Copy link
Copy Markdown
Contributor

Motivation & Context

Workflow agents expose executor lifecycle and external-input events through nested RawRepresentation values, but the AG-UI host did not translate those events into native AG-UI steps and interruptions. Consequently, workflow text and tool content could stream while clients lacked executor progress, resumable external-input handling, and correct terminal failure semantics.

This change adds native workflow mapping to the existing AG-UI hosting pipeline and provides runnable samples plus HTTP/SSE integration coverage for the supported scenarios.

Description & Review Guide

  • What are the major changes? The AG-UI endpoint retains the standard AsChatResponseUpdatesAsync() conversion, then applies an internal workflow transformation. Executor invocation/completion/failure becomes AG-UI step lifecycle; failed runs close active protocol streams and terminate with redacted RUN_ERROR; workflow request ports become AG-UI input interruptions whose responses resume persisted workflow sessions. Seven standalone client/server samples cover sequential, concurrent, failing, tool-enabled, nested, approval, and multiple-input workflows. Matching integration tests execute each sample topology through ASP.NET Core TestServer and the AG-UI HTTP/SSE protocol.
  • What is the impact of these changes? Workflow agents hosted with MapAGUIServer now expose native executor steps and workflow interruptions without an opt-in decorator. Existing text and tool conversion remains in the standard AG-UI pipeline. The nested-workflow sample characterizes the duplicate local executor-ID limitation tracked by .NET: Preserve nested executor identity in workflow lifecycle events #7763. The current terminal-error adapter compensates for AG-UI .NET 0.0.3 behavior and can be simplified after upstream AG-UI PR .NET: Updated package versions #2455 is released and consumed.
  • What do you want reviewers to focus on? Please focus on event ordering and balance across executor failure, interruption buffering before checkpoint persistence, partial/out-of-order multi-input resume, and the boundary between standard AG-UI conversion and workflow-specific mapping.

Related Issue

Fixes#2494

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
  • This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

@javiercn
Add workflow lifecycle mapping for AG-UI
febdce3
Map workflow supersteps and safe lifecycle metadata through an opt-in AG-UI agent decorator while preserving existing response, interrupt, tool, and error conversion behavior.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@javiercn
Scope AG-UI workflow mapping to executor steps
5ade34c
Map only executor invoked, completed, and failed workflow events in the AG-UI response stream. Preserve the existing conversion for every other update.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Map workflow events after chat conversion
a04cec0
Keep the standard AgentResponseUpdate to ChatResponseUpdate conversion and apply the minimal executor lifecycle mapping as a dedicated AG-UI stream transformation.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
CopilotAI balanced review requested due to automatic review settings August 18, 2026 17:52
@agent-framework-automationagent-framework-automationBot added the .NET Usage: [Issues, PRs], Target: .Net label Aug 18, 2026
CopilotAI reviewed Aug 18, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds native AG-UI step lifecycle events for .NET workflow executors.

Changes:

  • Maps executor invocation, completion, and failure to AG-UI step events.
  • Preserves failure error updates after closing the step.
  • Adds workflow dependencies and unit coverage.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file
FileDescription
WorkflowAGUIExtensionsTests.csTests lifecycle mapping and failure ordering.
Unit test .csprojReferences the workflow project.
WorkflowAGUIExtensions.csImplements workflow-to-AG-UI mapping.
Hosting .csprojAdds the workflow dependency.
AGUIEndpointRouteBuilderExtensions.csIntegrates mapping into the endpoint pipeline.

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

Comment threaddotnet/src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/WorkflowAGUIExtensions.cs
Comment on lines +15 to +16
internal static async IAsyncEnumerable<ChatResponseUpdate> MapWorkflowEventsToAGUI(
this IAsyncEnumerable<ChatResponseUpdate> updates)
github-actions[bot]
github-actionsBot reviewed Aug 18, 2026
View reviewed changes

@github-actionsgithub-actionsBot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (3 commit(s)): febdce30c765, 5ade34cbc74f, a04cec0ec4ba
Model:gpt-5.6-sol

Overview

The PR adds a focused post-conversion stream transform and preserves the existing error update after closing a failed executor step. Its unit tests cover the basic invoked, completed, failed, and pass-through cases. However, using an executor ID as the sole AG-UI step correlation key makes concurrent nested workflows with repeated child IDs emit ambiguous lifecycle pairs.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
1 verified finding remained after source verification (1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas:dotnet/src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/WorkflowAGUIExtensions.cs

Comment threaddotnet/src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/WorkflowAGUIExtensions.cs
switch (update.RawRepresentation)
{
case AgentResponseUpdate { RawRepresentation: ExecutorInvokedEvent invoked }:
update.RawRepresentation = new StepStartedEvent { StepName = invoked.ExecutorId };

@github-actionsgithub-actionsBotAug 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When concurrent nested workflows reuse a child executor ID, their forwarded events can produce overlapping steps with the same StepName, so clients cannot tell which invocation a StepFinishedEvent closes. Please qualify nested executor identities or propagate a per-invocation correlation value so every started step can be paired with its own terminal event.

Open
@javiercn
Add sequential workflow AG-UI sample
9416263
Demonstrate ordered executor step events through an AG-UI client/server sample and verify the sample workflow over HTTP/SSE.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Add concurrent workflow AG-UI sample
8634949
Demonstrate independent executor step lifecycles for concurrently running agents and verify the sample workflow over HTTP/SSE.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Add failing workflow AG-UI sample
778e346
Demonstrate balanced AG-UI step lifecycle events when a workflow executor fails and verify the sample over HTTP/SSE.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Add tool-enabled workflow AG-UI sample
84e8314
Demonstrate executor steps alongside backend tool calls, results, and text, with HTTP/SSE integration coverage preventing duplicate content.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Add nested workflow AG-UI sample
3a44f18
Characterize duplicate local executor IDs from parallel subworkflows and the resulting active-step collision tracked by issue #7763.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Add approval interruption workflow sample
ae70aa4
Map workflow input requests to AG-UI interruptions, preserve resumable workflow sessions, and demonstrate approval pause and resume over HTTP/SSE.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Add multiple-input workflow AG-UI sample
1d01a0e
Demonstrate three same-turn interruptions, partial out-of-order responses, persisted workflow state, and final completion after the remaining input arrives.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Make nested workflow collision deterministic
bc7bdc3
Synchronize the duplicate Analyze executors so the integration test reliably characterizes overlapping nested step IDs.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Terminate failed workflow runs with RUN_ERROR
670f132
Close active AG-UI message, reasoning, tool, and step streams before emitting terminal RUN_ERROR, and suppress the SDK's synthetic success outcome.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Remove unused workflow test imports
e7cb2e2
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercnJavier Calvarro Nelson (javiercn) changed the title .NET: Map workflow executor steps to AG-UI.NET: Map workflow lifecycle to AG-UIAug 19, 2026
@agent-framework-automationagent-framework-automationBot added the documentation Usage: [Issues, PRs], Target: documentation in the code base and learn docs label Aug 19, 2026
@agent-framework-automationagent-framework-automationBot added the workflows Usage: [Issues, PRs], Target: Workflows label Aug 19, 2026
@javiercn
Clarify workflow and remote agent sample roles
3f824b1
Show each server constructing a Workflow before adapting it with AsAIAgent, use Producer and Reviewer in the sequential scenario, and distinguish remote client agents and sessions by name.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Revert "Clarify workflow and remote agent sample roles"
3e5f838
This reverts commit 3f824b1.
@javiercn
Use IChatClient in workflow sample clients
0f04079
Call AGUIChatClient through the IChatClient abstraction directly and remove the unnecessary AIAgent and AgentSession client adapters.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
@javiercn
Use native tool approval in workflow sample
59ff780
Build the approval workflow around one expense-review agent with an explicit checklist and approval-required submission tool. Handle the native approval request/response pair through IChatClient, deduplicate the workflow-correlated request, and map generic interrupt responses unconditionally to function results.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 681114d3-3e0d-47f8-8b87-4e5873ecdd6d
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@github-actionsgithub-actions[bot]github-actions[bot] left review comments
Copilot code reviewCopilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@chetantoshniwalchetantoshniwalAwaiting requested review from chetantoshniwalchetantoshniwal will be requested when the pull request is marked ready for reviewchetantoshniwal is a code owner
@rogerbarretoRoger Barreto (rogerbarreto)Awaiting requested review from rogerbarretorogerbarreto will be requested when the pull request is marked ready for reviewrogerbarreto is a code owner
@SergeyMenshykhSergeyMenshykhAwaiting requested review from SergeyMenshykhSergeyMenshykh will be requested when the pull request is marked ready for reviewSergeyMenshykh is a code owner
@westey-mwestey (westey-m)Awaiting requested review from westey-mwestey-m will be requested when the pull request is marked ready for reviewwestey-m is a code owner
@peibekwePeter Ibekwe (peibekwe)Awaiting requested review from peibekwepeibekwe will be requested when the pull request is marked ready for reviewpeibekwe is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

documentationUsage: [Issues, PRs], Target: documentation in the code base and learn docs.NETUsage: [Issues, PRs], Target: .NetworkflowsUsage: [Issues, PRs], Target: Workflows

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

.NET: AG-UI support for workflow as agent

2 participants

@javiercn