Conditional edge routing sample.

2026-06-16 21:04:09 +08:00 · 2026-01-22 21:27:53 -08:00
parent 29fb22f7d8
commit 04fdf25019
12 changed files with 513 additions and 9 deletions
@@ -37,6 +37,7 @@
    <Project Path="samples/AzureFunctions/09_Workflow/09_Workflow.csproj" />
    <Project Path="samples/AzureFunctions/10_WorkflowConcurrent/10_WorkflowConcurrent.csproj" />
    <Project Path="samples/AzureFunctions/11_WorkflowSharedState/11_WorkflowSharedState.csproj" />
+    <Project Path="samples/AzureFunctions/12_ConditionalEdges/12_ConditionalEdges.csproj" />
  </Folder>
  <Folder Name="/Samples/DurableWorkflows/">
    <Project Path="samples/DurableWorkflows/01_ExecutorsAndEdges/01_ExecutorsAndEdges.csproj" />
@@ -1,4 +1,4 @@
-<Project Sdk="Microsoft.NET.Sdk">
+<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net10.0</TargetFrameworks>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
@@ -14,6 +14,10 @@
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

+  <ItemGroup>
+    <None Include="local.settings.json" />
+  </ItemGroup>
+
  <!-- Azure Functions packages -->
  <ItemGroup>
    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
@@ -0,0 +1,48 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
+    <OutputType>Exe</OutputType>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <!-- The Functions build tools don't like namespaces that start with a number -->
+    <AssemblyName>SingleAgent</AssemblyName>
+    <RootNamespace>SingleAgent</RootNamespace>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <FrameworkReference Include="Microsoft.AspNetCore.App" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="local.settings.json" />
+  </ItemGroup>
+
+  <!-- Azure Functions packages -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Azure.Functions.Worker" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask.AzureManaged" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" />
+    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <!-- Local projects that should be switched to package references when using the sample outside of this MAF repo -->
+  <!--
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI.Hosting.AzureFunctions" />
+    <PackageReference Include="Microsoft.Agents.AI.OpenAI" />
+  </ItemGroup>
+  -->
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Hosting.AzureFunctions\Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+  </ItemGroup>
+</Project>
@@ -0,0 +1,98 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use durable state management in Azure Functions workflows.
+// The OrderIdParserExecutor writes a value to shared state, and the FraudValidation reads it back.
+// The state is persisted durably using Durable Entities behind the scenes.
+
+using Microsoft.Agents.AI.Workflows;
+
+namespace SingleAgent;
+
+/// <summary>
+/// Constants for shared state scopes used across executors.
+/// </summary>
+internal static class SharedStateConstants
+{
+    public const string MessageScope = "MessageState";
+    public const string ProcessedMessageKey = "ProcessedMessage";
+}
+
+internal sealed class Order
+{
+    public Order(string id, decimal amount)
+    {
+        this.Id = id;
+        this.Amount = amount;
+    }
+    public string Id { get; }
+    public decimal Amount { get; }
+    public Customer? Customer { get; set; }
+    public string? PaymentReferenceNumber { get; set; }
+}
+
+public sealed record Customer(int Id, string Name, bool IsBlocked);
+
+internal sealed class OrderIdParserExecutor() : Executor<string, Order>("OrderIdParserExecutor")
+{
+    public override async ValueTask<Order> HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        return GetOrder(message);
+    }
+
+    private static Order GetOrder(string id)
+    {
+        // Simulate fetching order details
+        return new Order(id, 100.0m);
+    }
+}
+
+internal sealed class OrderEnrich() : Executor<Order, Order>("EnrichOrder")
+{
+    public override async ValueTask<Order> HandleAsync(Order message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        message.Customer = GetCustomerForOrder(message.Id);
+        return message;
+    }
+
+    private static Customer GetCustomerForOrder(string orderId)
+    {
+        if (orderId.Contains('B'))
+        {
+            return new Customer(101, "George", true);
+        }
+
+        return new Customer(201, "Jerry", false);
+    }
+}
+
+internal sealed class PaymentProcesserExecutor() : Executor<Order, Order>("PaymentProcesserExecutor")
+{
+    public override async ValueTask<Order> HandleAsync(Order message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // Call payment gateway.
+        message.PaymentReferenceNumber = Guid.NewGuid().ToString().Substring(0, 4);
+        return message;
+    }
+}
+
+internal sealed class NotifyFraudExecutor() : Executor<Order, string>("NotifyFraud")
+{
+    public override async ValueTask<string> HandleAsync(Order message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        // Notify fraud team.
+        return $"Order {message.Id} flagged as fraudulent for customer {message.Customer?.Name}.";
+    }
+}
+
+internal static class OrderRouteConditions
+{
+    /// <summary>
+    /// Returns a condition that evaluates to true when the customer is blocked.
+    /// </summary>
+    internal static Func<Order?, bool> WhenBlocked() => order => order?.Customer?.IsBlocked == true;
+
+    /// <summary>
+    /// Returns a condition that evaluates to true when the customer is not blocked.
+    /// </summary>
+    internal static Func<Order?, bool> WhenNotBlocked() => order => order?.Customer?.IsBlocked == false;
+}
@@ -0,0 +1,24 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI.Hosting.AzureFunctions;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Azure.Functions.Worker.Builder;
+using Microsoft.Extensions.Hosting;
+using SingleAgent;
+
+OrderIdParserExecutor orderParser = new();
+OrderEnrich orderEnrich = new();
+PaymentProcesserExecutor paymentProcessor = new();
+NotifyFraudExecutor notifyFraud = new();
+
+WorkflowBuilder builder = new(orderParser);
+builder.AddEdge(orderParser, orderEnrich);
+builder.AddEdge(orderEnrich, notifyFraud, condition: OrderRouteConditions.WhenBlocked());
+builder.AddEdge(orderEnrich, paymentProcessor, condition: OrderRouteConditions.WhenNotBlocked());
+
+var workflow = builder.WithName("ProcessOrder").Build();
+
+FunctionsApplication.CreateBuilder(args)
+    .ConfigureFunctionsWebApplication()
+    .ConfigureDurableOptions(options => options.Workflows.AddWorkflow(workflow))
+    .Build().Run();
@@ -0,0 +1,89 @@
+# Single Agent Sample
+
+This sample demonstrates how to use the Durable Agent Framework (DAFx) to create a simple Azure Functions app that hosts a single AI agent and provides direct HTTP API access for interactive conversations.
+
+## Key Concepts Demonstrated
+
+- Using the Microsoft Agent Framework to define a simple AI agent with a name and instructions.
+- Registering agents with the Function app and running them using HTTP.
+- Conversation management (via session IDs) for isolated interactions.
+
+## Environment Setup
+
+See the [README.md](../README.md) file in the parent directory for more information on how to configure the environment, including how to install and run common sample dependencies.
+
+## Running the Sample
+
+With the environment setup and function app running, you can test the sample by sending an HTTP request to the agent endpoint.
+
+You can use the `demo.http` file to send a message to the agent, or a command line tool like `curl` as shown below:
+
+Bash (Linux/macOS/WSL):
+
+```bash
+curl -X POST http://localhost:7071/api/agents/Joker/run \
+    -H "Content-Type: text/plain" \
+    -d "Tell me a joke about a pirate."
+```
+
+PowerShell:
+
+```powershell
+Invoke-RestMethod -Method Post `
+    -Uri http://localhost:7071/api/agents/Joker/run `
+    -ContentType text/plain `
+    -Body "Tell me a joke about a pirate."
+```
+
+You can also send JSON requests:
+
+```bash
+curl -X POST http://localhost:7071/api/agents/Joker/run \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json" \
+    -d '{"message": "Tell me a joke about a pirate."}'
+```
+
+To continue a conversation, include the `thread_id` in the query string or JSON body:
+
+```bash
+curl -X POST "http://localhost:7071/api/agents/Joker/run?thread_id=your-thread-id" \
+    -H "Content-Type: application/json" \
+    -H "Accept: application/json" \
+    -d '{"message": "Tell me another one."}'
+```
+
+The response from the agent will be displayed in the terminal where you ran `func start`. The expected `text/plain` output will look something like:
+
+```text
+Why don't pirates ever learn the alphabet? Because they always get stuck at "C"!
+```
+
+The expected `application/json` output will look something like:
+
+```json
+{
+  "status": 200,
+  "thread_id": "ee6e47a0-f24b-40b1-ade8-16fcebb9eb40",
+  "response": {
+    "Messages": [
+      {
+        "AuthorName": "Joker",
+        "CreatedAt": "2025-11-11T12:00:00.0000000Z",
+        "Role": "assistant",
+        "Contents": [
+          {
+            "Type": "text",
+            "Text": "Why don't pirates ever learn the alphabet? Because they always get stuck at 'C'!"
+          }
+        ]
+      }
+    ],
+    "Usage": {
+      "InputTokenCount": 78,
+      "OutputTokenCount": 36,
+      "TotalTokenCount": 114
+    }
+  }
+}
+```
@@ -0,0 +1,14 @@
+# Default endpoint address for local testing
+@authority=http://localhost:7071
+
+### Start the workflow
+POST {{authority}}/api/workflows/ProcessOrder/run
+Content-Type: text/plain
+
+B123
+
+### Start second workflow
+POST {{authority}}/api/workflows/ProcessOrder/run
+Content-Type: text/plain
+
+456
@@ -0,0 +1,20 @@
+{
+  "version": "2.0",
+  "logging": {
+    "logLevel": {
+      "Microsoft.Agents.AI.DurableTask": "Information",
+      "Microsoft.Agents.AI.Hosting.AzureFunctions": "Information",
+      "DurableTask": "Information",
+      "Microsoft.DurableTask": "Information"
+    }
+  },
+  "extensions": {
+    "durableTask": {
+      "hubName": "default",
+      "storageProvider": {
+        "type": "AzureManaged",
+        "connectionStringName": "DURABLE_TASK_SCHEDULER_CONNECTION_STRING"
+      }
+    }
+  }
+}
@@ -187,16 +187,25 @@ public class DurableWorkflowRunner

        foreach (WorkflowExecutionLevel level in plan.Levels)
        {
-            if (level.Executors.Count == 1)
+            // Filter executors based on edge conditions from their predecessors
+            List<WorkflowExecutorInfo> eligibleExecutors = GetEligibleExecutors(level.Executors, results, plan, logger);
+
+            if (eligibleExecutors.Count == 0)
            {
-                WorkflowExecutorInfo executorInfo = level.Executors[0];
+                // No eligible executors at this level, continue to next level
+                continue;
+            }
+
+            if (eligibleExecutors.Count == 1)
+            {
+                WorkflowExecutorInfo executorInfo = eligibleExecutors[0];
                string input = GetExecutorInput(executorInfo.ExecutorId, initialInput, results, plan);
                results[executorInfo.ExecutorId] = await this.ExecuteExecutorAsync(context, executorInfo, input, logger).ConfigureAwait(true);
            }
            else
            {
                List<Task<(string Id, string Result)>> tasks = [];
-                foreach (WorkflowExecutorInfo executorInfo in level.Executors)
+                foreach (WorkflowExecutorInfo executorInfo in eligibleExecutors)
                {
                    string input = GetExecutorInput(executorInfo.ExecutorId, initialInput, results, plan);
                    tasks.Add(this.ExecuteExecutorWithIdAsync(context, executorInfo, input, logger));
@@ -212,6 +221,115 @@ public class DurableWorkflowRunner
        return GetFinalResult(plan, results);
    }

+    /// <summary>
+    /// Filters executors based on their incoming edge conditions.
+    /// An executor is eligible if all its incoming edges have conditions that evaluate to true,
+    /// or if the edges have no conditions.
+    /// </summary>
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = "Deserializing workflow types registered at startup.")]
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = "Deserializing workflow types registered at startup.")]
+    private static List<WorkflowExecutorInfo> GetEligibleExecutors(
+        List<WorkflowExecutorInfo> executors,
+        Dictionary<string, string> results,
+        WorkflowExecutionPlan plan,
+        ILogger logger)
+    {
+        List<WorkflowExecutorInfo> eligible = [];
+
+        foreach (WorkflowExecutorInfo executorInfo in executors)
+        {
+            List<string> predecessors = plan.Predecessors[executorInfo.ExecutorId];
+
+            // Root executor (no predecessors) is always eligible
+            if (predecessors.Count == 0)
+            {
+                eligible.Add(executorInfo);
+                continue;
+            }
+
+            // Check if any predecessor's edge condition allows this executor to run
+            bool isEligible = false;
+            foreach (string predecessorId in predecessors)
+            {
+                // Get the condition for this edge (predecessor -> current executor)
+                if (!plan.EdgeConditions.TryGetValue((predecessorId, executorInfo.ExecutorId), out Func<object?, bool>? condition))
+                {
+                    // No condition registered for this edge, assume it's eligible
+                    isEligible = true;
+                    break;
+                }
+
+                if (condition is null)
+                {
+                    // Edge has no condition, always eligible
+                    isEligible = true;
+                    break;
+                }
+
+                // Evaluate the condition using the predecessor's result
+                if (results.TryGetValue(predecessorId, out string? predecessorResult))
+                {
+                    try
+                    {
+                        // Get the predecessor's output type for proper deserialization
+                        Type? predecessorOutputType = plan.ExecutorOutputTypes.GetValueOrDefault(predecessorId);
+
+                        // Deserialize the predecessor result to the expected type for condition evaluation
+                        object? resultObject = DeserializeForCondition(predecessorResult, predecessorOutputType);
+                        if (condition(resultObject))
+                        {
+                            isEligible = true;
+                            break;
+                        }
+                    }
+                    catch (Exception ex)
+                    {
+                        logger.LogWarning(ex, "Failed to evaluate condition for edge from '{PredecessorId}' to '{ExecutorId}'", predecessorId, executorInfo.ExecutorId);
+                    }
+                }
+            }
+
+            if (isEligible)
+            {
+                eligible.Add(executorInfo);
+            }
+            else
+            {
+                logger.LogExecutorSkipped(executorInfo.ExecutorId);
+            }
+        }
+
+        return eligible;
+    }
+
+    /// <summary>
+    /// Deserializes a JSON string result into an object for condition evaluation.
+    /// </summary>
+    [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;
+        }
+
+        try
+        {
+            if (targetType is null)
+            {
+                return JsonSerializer.Deserialize<object>(json);
+            }
+
+            return JsonSerializer.Deserialize(json, targetType);
+        }
+        catch (JsonException)
+        {
+            // If it's not valid JSON, return the string as-is
+            return json;
+        }
+    }
+
    private async Task<(string Id, string Result)> ExecuteExecutorWithIdAsync(
        TaskOrchestrationContext context,
        WorkflowExecutorInfo executorInfo,
@@ -130,4 +130,10 @@ internal static partial class Logs
        Level = LogLevel.Information,
        Message = "Activity executed for executor '{ExecutorId}' with result: {Result}")]
    public static partial void LogActivityExecuted(this ILogger logger, string executorId, string result);
+
+    [LoggerMessage(
+        EventId = 17,
+        Level = LogLevel.Information,
+        Message = "Executor '{ExecutorId}' skipped due to edge condition evaluation")]
+    public static partial void LogExecutorSkipped(this ILogger logger, string executorId);
 }
@@ -41,6 +41,17 @@ public sealed class WorkflowExecutionPlan
    /// </summary>
    public Dictionary<string, List<string>> Successors { 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; } = [];
+
    /// <summary>
    /// Gets whether this workflow has any parallel execution opportunities.
    /// </summary>
@@ -89,6 +100,7 @@ public static class WorkflowHelper

        Dictionary<string, ExecutorBinding> executors = workflow.ReflectExecutors();
        Dictionary<string, HashSet<EdgeInfo>> edges = workflow.ReflectEdges();
+        Dictionary<(string SourceId, string TargetId), Func<object?, bool>?> edgeConditions = workflow.GetEdgeConditions();

        WorkflowExecutionPlan plan = new();

@@ -97,12 +109,15 @@ public static class WorkflowHelper
        Dictionary<string, List<string>> predecessors = [];
        Dictionary<string, int> inDegree = [];

-        // Initialize all executors
-        foreach (string executorId in executors.Keys)
+        // Initialize all executors and extract their output types
+        foreach (KeyValuePair<string, ExecutorBinding> executor in executors)
        {
-            successors[executorId] = [];
-            predecessors[executorId] = [];
-            inDegree[executorId] = 0;
+            successors[executor.Key] = [];
+            predecessors[executor.Key] = [];
+            inDegree[executor.Key] = 0;
+
+            // Extract output type from executor type (e.g., Executor<TInput, TOutput> -> TOutput)
+            plan.ExecutorOutputTypes[executor.Key] = GetExecutorOutputType(executor.Value.ExecutorType);
        }

        // Build the graph from edges
@@ -124,6 +139,12 @@ public static class WorkflowHelper
            }
        }

+        // Store edge conditions in the plan
+        foreach (KeyValuePair<(string SourceId, string TargetId), Func<object?, bool>?> condition in edgeConditions)
+        {
+            plan.EdgeConditions[condition.Key] = condition.Value;
+        }
+
        // Store the graph structure in the plan
        foreach (string executorId in executors.Keys)
        {
@@ -213,4 +234,41 @@ public static class WorkflowHelper
        return typeName.Contains("AIAgentHostExecutor", StringComparison.OrdinalIgnoreCase) &&
                assemblyName.Contains("Microsoft.Agents.AI", StringComparison.OrdinalIgnoreCase);
    }
+
+    /// <summary>
+    /// Extracts the output type from an executor type.
+    /// For Executor&lt;TInput, TOutput&gt;, returns TOutput.
+    /// For Executor&lt;TInput&gt;, returns null (void output).
+    /// </summary>
+    /// <param name="executorType">The executor type to analyze.</param>
+    /// <returns>The output type, or null if the executor has no typed output.</returns>
+    private static Type? GetExecutorOutputType(Type executorType)
+    {
+        // Walk up the inheritance chain to find Executor<TInput, TOutput> or Executor<TInput>
+        Type? currentType = executorType;
+        while (currentType is not null)
+        {
+            if (currentType.IsGenericType)
+            {
+                Type genericDefinition = currentType.GetGenericTypeDefinition();
+                Type[] genericArgs = currentType.GetGenericArguments();
+
+                // Check for Executor<TInput, TOutput> (2 type parameters)
+                if (genericArgs.Length == 2 && genericDefinition.Name.StartsWith("Executor", StringComparison.Ordinal))
+                {
+                    return genericArgs[1]; // TOutput
+                }
+
+                // Check for Executor<TInput> (1 type parameter) - void return
+                if (genericArgs.Length == 1 && genericDefinition.Name.StartsWith("Executor", StringComparison.Ordinal))
+                {
+                    return null;
+                }
+            }
+
+            currentType = currentType.BaseType;
+        }
+
+        return null;
+    }
 }
@@ -35,6 +35,30 @@ public class Workflow
        );
    }

+    /// <summary>
+    /// Gets the condition functions for direct edges, keyed by (sourceId, targetId) tuple.
+    /// </summary>
+    /// <returns>A dictionary mapping edge connections to their condition functions (null if no condition).</returns>
+    /// <remarks>This method creates a new dictionary each time it is called to ensure thread safety.</remarks>
+    [System.Diagnostics.CodeAnalysis.SuppressMessage("Design", "CA1024:Use properties where appropriate", Justification = "Method creates a new collection on each call.")]
+    public Dictionary<(string SourceId, string TargetId), Func<object?, bool>?> GetEdgeConditions()
+    {
+        Dictionary<(string SourceId, string TargetId), Func<object?, bool>?> conditions = [];
+
+        foreach (KeyValuePair<string, HashSet<Edge>> edgeGroup in this.Edges)
+        {
+            foreach (Edge edge in edgeGroup.Value)
+            {
+                if (edge.DirectEdgeData is DirectEdgeData directEdge)
+                {
+                    conditions[(directEdge.SourceId, directEdge.SinkId)] = directEdge.Condition;
+                }
+            }
+        }
+
+        return conditions;
+    }
+
    /// <summary>
    /// Gets all executor bindings in the workflow, keyed by their ID.
    /// </summary>