.NET: Add Declarative Workflow Interpreter (microsoft#401)

* test: Add Reflection/Invocation tests

* fix: Terminate on Completion event

* refactor: Update public API surface

* feat: Add support for external requests

* feat: Support hosting AIAgent instances in Workflows

* fix: Fix routing to go through Executor.ExecuteAsync

* test: Update samples for "must SendMessage" semantics

* Add invoking samples to unit tests to avoid future breaks

* fix: ExternalRequest should block Workflow completion

* feat: Normalize API surface against Python

* Also adds xmldoc to all public APIs

* refactor: Normalize UnitTest and Sample namespaces

* fix: Formatting

* refactor: Normalize project/folder names

* feat: Remove DynamicCodeExecution from ValueTaskTypeErasure

* fix: Fix ILTrim warnings

* docs: Add missing docs and fix typos

* feat: Hosted Agents should report Run events

* fix: Fix type propagation for ILTrim changes

* refactor: Simplify DynamicallyAccessedMembers annotations

* sample: Use static-Type construction of InputPort

* feat: Support non-Streaming Run Mode

* test: Add test for non-streaming execution

* Conversion checkpoint

* Fix namespace error

* Restructure

* Completion

* Executor checkpoint

* Conditional checkpoint

* Cleanup

* Exception cleanup

* Sample cleanup

* Updates

* feat: Define Workflow and Executor APIs

* feat: Define IExecutionContext and Events

* feat: Simple Workflow Demos

* refactor: Move Workflows classes to separate assembly

* feat: Move FanOut/In to LowLevel API with new semantics

* feat: Implement Local Execution

* refactor: Assembly name .Workflow => .Workflows

* feat: Enable Default Message Handling

* also lifts Bind in MessageHandlerInfo to better be able to direclty invoke handlers (for AOT, later)

* feat: Implement StreamingHandle APIs

This allows the user to respond to WorkflowEvents with external messages, enabling HIL.

* feat: Add checks for duplicate edges and chain cycles

* feat: Add built-in WorkflowEvents

* refactor: Pull classes into own files

* refactor: Simplify Disposal pattern in Executor

* refactor: Break EdgeRunner file into per-type files

* refactor: Use Throw.IfNull()

* refactor: Remove AddLoop()

Per microsoft#272 (comment) we decided this was not very useful.

* refactor: Normalize use of ValueTask

* fix: Build Break from removing .AddLoop

* refactor: Explicit routing and RouteBuilder

Split out reflection from MessageRouter implemention into build phase, enabling AOT compilation to drive RouteBuilding without reflection.

* test: Add Reflection/Invocation tests

* fix: Terminate on Completion event

* refactor: Update public API surface

* feat: Add support for external requests

* feat: Support hosting AIAgent instances in Workflows

* fix: Fix routing to go through Executor.ExecuteAsync

* test: Update samples for "must SendMessage" semantics

* Add invoking samples to unit tests to avoid future breaks

* fix: ExternalRequest should block Workflow completion

* feat: Normalize API surface against Python

* Also adds xmldoc to all public APIs

* refactor: Normalize UnitTest and Sample namespaces

* fix: Formatting

* refactor: Normalize project/folder names

* feat: Remove DynamicCodeExecution from ValueTaskTypeErasure

* fix: Fix ILTrim warnings

* docs: Add missing docs and fix typos

* feat: Hosted Agents should report Run events

* fix: Fix type propagation for ILTrim changes

* refactor: Simplify DynamicallyAccessedMembers annotations

* sample: Use static-Type construction of InputPort

* feat: Support non-Streaming Run Mode

* test: Add test for non-streaming execution

* refactor: Remove unused types

* refactor: Simplify Event and EdgeData type hierarchies

* feat: Add Switch (=Conditional Edge Group) control flow

* Fix unit-tests

* Add sample

* Comment cleanup

* Fix debug output

* Formating helpers

* feat: Define Workflow and Executor APIs

* feat: Define IExecutionContext and Events

* feat: Simple Workflow Demos

* refactor: Move Workflows classes to separate assembly

* feat: Move FanOut/In to LowLevel API with new semantics

* feat: Implement Local Execution

* refactor: Assembly name .Workflow => .Workflows

* feat: Enable Default Message Handling

* also lifts Bind in MessageHandlerInfo to better be able to direclty invoke handlers (for AOT, later)

* feat: Implement StreamingHandle APIs

This allows the user to respond to WorkflowEvents with external messages, enabling HIL.

* feat: Add checks for duplicate edges and chain cycles

* feat: Add built-in WorkflowEvents

* refactor: Pull classes into own files

* refactor: Simplify Disposal pattern in Executor

* refactor: Break EdgeRunner file into per-type files

* refactor: Use Throw.IfNull()

* refactor: Remove AddLoop()

Per microsoft#272 (comment) we decided this was not very useful.

* refactor: Normalize use of ValueTask

* fix: Build Break from removing .AddLoop

* refactor: Explicit routing and RouteBuilder

Split out reflection from MessageRouter implemention into build phase, enabling AOT compilation to drive RouteBuilding without reflection.

* test: Add Reflection/Invocation tests

* fix: Terminate on Completion event

* refactor: Update public API surface

* feat: Add support for external requests

* feat: Support hosting AIAgent instances in Workflows

* fix: Fix routing to go through Executor.ExecuteAsync

* test: Update samples for "must SendMessage" semantics

* Add invoking samples to unit tests to avoid future breaks

* fix: ExternalRequest should block Workflow completion

* feat: Normalize API surface against Python

* Also adds xmldoc to all public APIs

* refactor: Normalize UnitTest and Sample namespaces

* fix: Formatting

* refactor: Normalize project/folder names

* feat: Remove DynamicCodeExecution from ValueTaskTypeErasure

* fix: Fix ILTrim warnings

* docs: Add missing docs and fix typos

* feat: Hosted Agents should report Run events

* fix: Fix type propagation for ILTrim changes

* refactor: Simplify DynamicallyAccessedMembers annotations

* sample: Use static-Type construction of InputPort

* feat: Support non-Streaming Run Mode

* test: Add test for non-streaming execution

* refactor: Remove unused types

* refactor: Simplify Event and EdgeData type hierarchies

* feat: Add Switch (=Conditional Edge Group) control flow

* feat: Make .NET AutoSend the MessageHandler result

* feat: Implement State APIs

* Add tests

* Fix merge from main

* Test coverage

* Message event

* Comments and clean-up

* Format

* Cleanup

* Test checkpoint

* Clean-up - comments / test

* Test baseline - 100%

* More clean-up

* Comments

* Streaming...sort've...

* Fix build / test

* Stable

* Checkpoint

* Checkpoint

* Stable

* Update sample after merge

* Add "Question" workflow

* State clean-up checkpoint

* State clean-up

* Sample updated

* Expression bug fix

* Sample formatting

* Add unit test

* Comments

* Scope cleanup

* Refine cleanup

* Fill gaps

* fcs

* Finalize data-types

* Add unit-test

* Debug cleanup

* Bug fixes

* Demo progress

* Sample clean-up

* Update samples

* Sample updates

* Sync demo workflows

* Sample formatting

* Sample formatting

* Demo complete

* Workflow formatting

* Demo formatting microsoft#2

* Readme + Sample clean-up

* Scope update

* Update diagnostics

* Variable initiaization

* Rollback

* Tune research summary

* State management

* Fix merge

* Fix merge - demo

* Add readme

* Overload for workflow builder

* Fault tolerance - scope equivalency

* Fix feed

* Update sample

* Add default for "Bot"

* Nuget.config patchwork

* Scope assignment check

* Rollback nuget.config haxx

* Sample format

* Namespace

* Namespace

* Agent-Provider

* Clean-up extra files

* Renaming

* Update sample

* Prune junk files

* Clean-up

* Use transform

* agent provider fix

* Typo

* Null check fix

* Fix merge

* Checkpoint

* Cleanup

* Exception cleanup

* Exception message

* Clean-up

* Sample config update

* Update handling of "Env" scope

* Sample agent templates

* Add readme

* Event cleanup

* Rename event

* Update workflows/README.md

Co-authored-by: Eric Zhu <ekzhu@users.noreply.github.com>

---------

Co-authored-by: Jacob Alber <jaalber@microsoft.com>
Co-authored-by: Eric Zhu <ekzhu@users.noreply.github.com>

Author: 3 people

dotnet/Directory.Packages.props

@@ -80,6 +80,11 @@
     <PackageVersion Include="Microsoft.ML.OnnxRuntimeGenAI" Version="0.9.0" />
     <!-- Identity -->
     <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.74.1" />
+    <!-- Workflows -->
+    <PackageVersion Include="Microsoft.Bot.ObjectModel" Version="2025.8.2-1" />
+    <PackageVersion Include="Microsoft.Bot.ObjectModel.Json" Version="2025.8.2-1" />
+    <PackageVersion Include="Microsoft.Bot.ObjectModel.PowerFx" Version="2025.8.2-1" />
+    <PackageVersion Include="Microsoft.PowerFx.Interpreter" Version="1.4.0-build.20250625-1002" />
     <!-- Test -->
     <PackageVersion Include="FluentAssertions" Version="8.5.0" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />

dotnet/agent-framework-dotnet.slnx

@@ -44,6 +44,17 @@
   <Folder Name="/Samples/GettingStarted/Telemetry/">
     <Project Path="samples/GettingStarted/AgentOpenTelemetry/AgentOpenTelemetry.csproj" />
   </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/">
+    <Project Path="samples/DeclarativeWorkflow/DeclarativeWorkflow.csproj" />
+  </Folder>
+  <Folder Name="/Samples/GettingStarted/Workflows/Example/">
+    <File Path="../workflows/DeepResearch.yaml" />
+    <File Path="../workflows/HelloWorld.yaml" />
+    <File Path="../workflows/MathChat.yaml" />
+    <File Path="../workflows/Question.yaml" />
+    <File Path="../workflows/README.md" />
+    <File Path="../workflows/wttr.json" />
+  </Folder>
   <Folder Name="/Samples/SemanticKernelMigration/" />
   <Folder Name="/Samples/SemanticKernelMigration/AzureAIFoundry/">
     <Project Path="samples/SemanticKernelMigration/AzureAIFoundry/Step01_Basics/AzureAIFoundry_Step01_Basics.csproj" />
@@ -80,6 +91,8 @@
     <File Path="Directory.Build.props" />
     <File Path="Directory.Build.targets" />
     <File Path="Directory.Packages.props" />
+    <File Path="global.json" />
+    <File Path="nuget.config" />
   </Folder>
   <Folder Name="/Solution Items/.github/" />
   <Folder Name="/Solution Items/.github/workflows/">
@@ -175,6 +188,7 @@
   </Folder>
   <Folder Name="/src/">
     <Project Path="src/Microsoft.Agents.Orchestration/Microsoft.Agents.Orchestration.csproj" />
+    <Project Path="src/Microsoft.Agents.Workflows.Declarative/Microsoft.Agents.Workflows.Declarative.csproj" />
     <Project Path="src/Microsoft.Agents.Workflows/Microsoft.Agents.Workflows.csproj" />
     <Project Path="src/Microsoft.Extensions.AI.Agents.A2A/Microsoft.Extensions.AI.Agents.A2A.csproj" />
     <Project Path="src/Microsoft.Extensions.AI.Agents.Abstractions/Microsoft.Extensions.AI.Agents.Abstractions.csproj" />
@@ -204,6 +218,7 @@
   </Folder>
   <Folder Name="/Tests/UnitTests/">
     <Project Path="tests/Microsoft.Agents.Orchestration.UnitTests/Microsoft.Agents.Orchestration.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.Workflows.Declarative.UnitTests/Microsoft.Agents.Workflows.Declarative.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.Workflows.UnitTests/Microsoft.Agents.Workflows.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Extensions.AI.Agents.A2A.UnitTests/Microsoft.Extensions.AI.Agents.A2A.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Extensions.AI.Agents.Abstractions.UnitTests/Microsoft.Extensions.AI.Agents.Abstractions.UnitTests.csproj" />

dotnet/nuget.config

@@ -2,6 +2,16 @@
 <configuration>
   <packageSources>
     <clear />
-    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />  
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
+    <add key="CopilotStudio" value="https://pkgs.dev.azure.com/Power-Fx/7dd30b4a-31be-4ac9-a649-e6addd4d5b0a/_packaging/CopilotStudio/nuget/v3/index.json" />
   </packageSources>
+  <packageSourceMapping>
+    <packageSource key="nuget.org">
+      <package pattern="*" />
+    </packageSource>
+    <packageSource key="CopilotStudio">
+      <package pattern="Microsoft.Bot.*" />
+      <package pattern="Microsoft.PowerFx.*" />
+    </packageSource>
+  </packageSourceMapping>
 </configuration>

dotnet/samples/DeclarativeWorkflow/DeclarativeWorkflow.csproj

@@ -0,0 +1,33 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net9.0</TargetFrameworks>
+    <ProjectsDebugTargetFrameworks>net9.0</ProjectsDebugTargetFrameworks>
+    <TargetFrameworks Condition="'$(Configuration)' == 'Debug'">$(ProjectsDebugTargetFrameworks)</TargetFrameworks>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>disable</ImplicitUsings>
+    <UserSecretsId>5ee045b0-aea3-4f08-8d31-32d1a6f8fed0</UserSecretsId>
+    <NoWarn>$(NoWarn);CA1812</NoWarn>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <InjectSharedThrow>true</InjectSharedThrow>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.Configuration" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Binder" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.Json" />
+    <PackageReference Include="Microsoft.Extensions.Configuration.UserSecrets" />
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
+    <PackageReference Include="Microsoft.Extensions.Logging" />
+  </ItemGroup>
+  
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Microsoft.Agents.Workflows\Microsoft.Agents.Workflows.csproj" />
+    <ProjectReference Include="..\..\src\Microsoft.Agents.Workflows.Declarative\Microsoft.Agents.Workflows.Declarative.csproj" />
+  </ItemGroup>
+
+</Project>