Skip to content

Commit 1b9879c

Browse files
authored
.NET: feat(dotnet): support closed-list workflow questions (#9202)
* feat(dotnet): support embedded closed list entities in declarative Question A Question with an EmbeddedEntity whose definition is a ClosedListEntity fell through to UnsupportedEntity, so every answer was rejected and the variable was only ever set through the retry default. EntityExtractor now matches the trimmed answer case-insensitively against each item's display name and synonyms, then against the item id, and captures the matched item's id. That is the same string an option set value already converts to in DataValueExtensions. Other embedded entity definitions still report as unsupported, now naming the definition type. Refs: #1530 * fix(dotnet): save question fixture with utf-8 bom
1 parent dcbbf79 commit 1b9879c

4 files changed

Lines changed: 309 additions & 0 deletions

File tree

‎dotnet/src/Microsoft.Agents.AI.Workflows.Declarative/Entities/EntityExtractor.cs‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
// Copyright (c) Microsoft. All rights reserved.
22

33
using System;
4+
using System.Linq;
45
using System.Net.Mail;
56
using System.Text.RegularExpressions;
67
using Microsoft.Agents.ObjectModel;
@@ -35,6 +36,7 @@ public static EntityExtractionResult Parse(EntityReference? entity, string value
3536
DateTimePrebuiltEntity => TryParseDateTime(value),
3637
DurationPrebuiltEntity => TryParseDuration(value),
3738
EmailPrebuiltEntity => TryParseEmail(value),
39+
EmbeddedEntity embeddedEntity => TryParseEmbedded(embeddedEntity, value),
3840
EventPrebuiltEntity => TryParseString(value),
3941
LanguagePrebuiltEntity => TryParseString(value),
4042
MoneyPrebuiltEntity => TryParseNumberUnit(value, "money"),
@@ -117,6 +119,33 @@ private static EntityExtractionResult TryParseEmail(string value)
117119
}
118120
}
119121

122+
private static EntityExtractionResult TryParseEmbedded(EmbeddedEntity entity, string value) =>
123+
entity.Definition switch
124+
{
125+
ClosedListEntity closedListEntity => TryParseClosedList(closedListEntity, value),
126+
_ => new EntityExtractionResult($"Unsupported embedded entity: {entity.Definition?.GetType().Name ?? "undefined"}"),
127+
};
128+
129+
private static EntityExtractionResult TryParseClosedList(ClosedListEntity entity, string value)
130+
{
131+
// Match on display name or synonym before item id; the selected item is captured by its id,
132+
// the same as an option set value (see DataValueExtensions).
133+
string input = value.Trim();
134+
ClosedListItem? selectedItem =
135+
entity.Items.FirstOrDefault(item => IsMatch(item.DisplayName, input) || item.Synonyms.Any(synonym => IsMatch(synonym, input))) ??
136+
entity.Items.FirstOrDefault(item => IsMatch(item.Id.Value, input));
137+
138+
if (selectedItem is not null)
139+
{
140+
return new EntityExtractionResult(FormulaValue.New(selectedItem.Id.Value));
141+
}
142+
143+
return new EntityExtractionResult($"Invalid choice value: {value}");
144+
145+
static bool IsMatch(string? candidate, string input) =>
146+
input.Length > 0 && string.Equals(candidate?.Trim(), input, StringComparison.OrdinalIgnoreCase);
147+
}
148+
120149
private static EntityExtractionResult TryParseNumberUnit(string value, string type)
121150
{
122151
Match m = NumberUnitRegex().Match(value);

‎dotnet/tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Entities/EntityExtractorTest.cs‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -681,6 +681,105 @@ public void Parse_StringEntity_ValidValue_ReturnsString(string value)
681681
Assert.Equal(value, (result.Value as StringValue)?.Value);
682682
}
683683

684+
[Theory]
685+
[InlineData("red", "option-1")]
686+
[InlineData("RED", "option-1")]
687+
[InlineData(" red ", "option-1")]
688+
[InlineData("crimson", "option-1")]
689+
[InlineData("Scarlet", "option-1")]
690+
[InlineData("yello", "option-2")]
691+
[InlineData("option-2", "option-2")]
692+
[InlineData("OPTION-1", "option-1")]
693+
public void Parse_EmbeddedClosedListEntity_ValidValue_ReturnsItemId(string value, string expectedId)
694+
{
695+
// Arrange
696+
EntityReference entity = CreateClosedListEntity();
697+
698+
// Act
699+
EntityExtractionResult result = EntityExtractor.Parse(entity, value);
700+
701+
// Assert
702+
Assert.True(result.IsValid);
703+
Assert.Equal(expectedId, (result.Value as StringValue)?.Value);
704+
}
705+
706+
[Theory]
707+
[InlineData("purple")]
708+
[InlineData("re")]
709+
[InlineData("red yello")]
710+
[InlineData("")]
711+
[InlineData(" ")]
712+
public void Parse_EmbeddedClosedListEntity_InvalidValue_ReturnsError(string value)
713+
{
714+
// Arrange
715+
EntityReference entity = CreateClosedListEntity();
716+
717+
// Act
718+
EntityExtractionResult result = EntityExtractor.Parse(entity, value);
719+
720+
// Assert
721+
Assert.False(result.IsValid);
722+
Assert.Null(result.Value);
723+
Assert.Contains("Invalid choice", result.ErrorMessage);
724+
}
725+
726+
[Fact]
727+
public void Parse_EmbeddedClosedListEntity_DisplayNameTakesPrecedenceOverId()
728+
{
729+
// Arrange
730+
EntityReference entity =
731+
new EmbeddedEntity.Builder
732+
{
733+
Definition = new ClosedListEntity.Builder
734+
{
735+
Items =
736+
{
737+
new ClosedListItem.Builder { Id = new ClosedListItemId("blue"), DisplayName = "Navy" },
738+
new ClosedListItem.Builder { Id = new ClosedListItemId("sky"), DisplayName = "Blue" },
739+
},
740+
},
741+
}.Build();
742+
743+
// Act
744+
EntityExtractionResult result = EntityExtractor.Parse(entity, "blue");
745+
746+
// Assert
747+
Assert.True(result.IsValid);
748+
Assert.Equal("sky", (result.Value as StringValue)?.Value);
749+
}
750+
751+
[Fact]
752+
public void Parse_EmbeddedEntity_UnsupportedDefinition_ReturnsError()
753+
{
754+
// Arrange
755+
EntityReference entity =
756+
new EmbeddedEntity.Builder
757+
{
758+
Definition = new RegexEntity.Builder { Pattern = "[a-z]+" },
759+
}.Build();
760+
761+
// Act
762+
EntityExtractionResult result = EntityExtractor.Parse(entity, "abc");
763+
764+
// Assert
765+
Assert.False(result.IsValid);
766+
Assert.Equal($"Unsupported embedded entity: {nameof(RegexEntity)}", result.ErrorMessage);
767+
}
768+
769+
private static EmbeddedEntity CreateClosedListEntity() =>
770+
new EmbeddedEntity.Builder
771+
{
772+
DisplayName = "Multiple choice",
773+
Definition = new ClosedListEntity.Builder
774+
{
775+
Items =
776+
{
777+
new ClosedListItem.Builder { Id = new ClosedListItemId("option-1"), DisplayName = "red", Synonyms = { "crimson", "scarlet" } },
778+
new ClosedListItem.Builder { Id = new ClosedListItemId("option-2"), DisplayName = "yello" },
779+
},
780+
},
781+
}.Build();
782+
684783
private static BooleanPrebuiltEntity CreateBooleanEntity() =>
685784
new BooleanPrebuiltEntity.Builder().Build();
686785

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
3+
using System;
4+
using System.Collections.Generic;
5+
using System.IO;
6+
using System.Linq;
7+
using System.Threading.Tasks;
8+
using Microsoft.Agents.AI.Workflows.Checkpointing;
9+
using Microsoft.Agents.AI.Workflows.Declarative.Events;
10+
using Microsoft.Extensions.AI;
11+
using Xunit.Sdk;
12+
13+
namespace Microsoft.Agents.AI.Workflows.Declarative.UnitTests;
14+
15+
/// <summary>
16+
/// Tests the request / response flow of a <c>Question</c> action defined in a declarative workflow,
17+
/// resuming from a JSON checkpoint for each response.
18+
/// </summary>
19+
public sealed class QuestionWorkflowTest(ITestOutputHelper output) : WorkflowTest(output)
20+
{
21+
private const string ClosedListWorkflow = "QuestionClosedList.yaml";
22+
23+
[Theory]
24+
[InlineData("red", "option-1")]
25+
[InlineData("Crimson", "option-1")]
26+
[InlineData(" YELLO ", "option-2")]
27+
[InlineData("option-2", "option-2")]
28+
public async Task QuestionClosedListCapturesSelectedItemAsync(string response, string expectedItemId)
29+
{
30+
// Act
31+
List<WorkflowEvent> events = await this.RunWorkflowAsync(ClosedListWorkflow, response);
32+
33+
// Assert
34+
Assert.Single(events.OfType<RequestInfoEvent>());
35+
Assert.DoesNotContain(events.OfType<MessageActivityEvent>(), e => e.Message.Contains("Please pick one", StringComparison.Ordinal));
36+
AssertMessage(events, $"Selected: \"{expectedItemId}\"");
37+
}
38+
39+
[Fact]
40+
public async Task QuestionClosedListRepromptsOnUnknownItemAsync()
41+
{
42+
// Act
43+
List<WorkflowEvent> events = await this.RunWorkflowAsync(ClosedListWorkflow, "purple", "red");
44+
45+
// Assert
46+
Assert.Equal(2, events.OfType<RequestInfoEvent>().Count());
47+
AssertMessage(events, "Please pick one of the listed colors.");
48+
Assert.DoesNotContain(events.OfType<MessageActivityEvent>(), e => e.Message.Contains("using the default", StringComparison.Ordinal));
49+
AssertMessage(events, "Selected: \"option-1\"");
50+
}
51+
52+
[Fact]
53+
public async Task QuestionClosedListAssignsDefaultAfterRepeatCountAsync()
54+
{
55+
// Act
56+
List<WorkflowEvent> events = await this.RunWorkflowAsync(ClosedListWorkflow, "purple", "blue");
57+
58+
// Assert
59+
Assert.Equal(2, events.OfType<RequestInfoEvent>().Count());
60+
AssertMessage(events, "No valid color selected, using the default.");
61+
AssertMessage(events, "Selected: \"option-2\"");
62+
}
63+
64+
private static void AssertMessage(List<WorkflowEvent> events, string message) =>
65+
Assert.Contains(events.OfType<MessageActivityEvent>(), e => string.Equals(e.Message.Trim(), message, StringComparison.Ordinal));
66+
67+
private async Task<List<WorkflowEvent>> RunWorkflowAsync(string workflowFile, params string[] responses)
68+
{
69+
DirectoryInfo checkpointFolder = Directory.CreateDirectory(Path.Combine(Path.GetTempPath(), $"af-question-{Guid.NewGuid():N}"));
70+
try
71+
{
72+
using FileSystemJsonCheckpointStore store = new(checkpointFolder);
73+
CheckpointManager checkpointManager = CheckpointManager.CreateJson(store, DeclarativeWorkflowJsonOptions.Default);
74+
75+
List<WorkflowEvent> events = [];
76+
(RequestInfoEvent? request, CheckpointInfo? checkpoint) = await this.WatchAsync(
77+
await InProcessExecution.RunStreamingAsync(this.CreateWorkflow(workflowFile), "start", checkpointManager),
78+
response: null,
79+
events);
80+
81+
foreach (string responseText in responses)
82+
{
83+
Assert.NotNull(request);
84+
Assert.NotNull(checkpoint);
85+
86+
// Resume a freshly built workflow from the checkpoint to exercise pause / resume.
87+
ExternalResponse response = request.Request.CreateResponse(new ExternalInputResponse(new ChatMessage(ChatRole.User, responseText)));
88+
(request, checkpoint) = await this.WatchAsync(
89+
await InProcessExecution.ResumeStreamingAsync(this.CreateWorkflow(workflowFile), checkpoint, checkpointManager),
90+
response,
91+
events);
92+
}
93+
94+
Assert.Null(request);
95+
return events;
96+
}
97+
finally
98+
{
99+
checkpointFolder.Delete(recursive: true);
100+
}
101+
}
102+
103+
private async Task<(RequestInfoEvent? Request, CheckpointInfo? Checkpoint)> WatchAsync(StreamingRun run, ExternalResponse? response, List<WorkflowEvent> events)
104+
{
105+
await using StreamingRun _ = run;
106+
107+
if (response is not null)
108+
{
109+
await run.SendResponseAsync(response);
110+
}
111+
112+
RequestInfoEvent? request = null;
113+
CheckpointInfo? checkpoint = null;
114+
await foreach (WorkflowEvent workflowEvent in run.WatchStreamAsync(blockOnPendingRequest: false))
115+
{
116+
switch (workflowEvent)
117+
{
118+
case RequestInfoEvent requestEvent when requestEvent.Request.RequestId != response?.RequestId:
119+
ExternalInputRequest inputRequest = Assert.IsType<ExternalInputRequest>(requestEvent.Request.Data.As<ExternalInputRequest>());
120+
this.Output.WriteLine($"REQUEST: {inputRequest.AgentResponse.Text}");
121+
request = requestEvent;
122+
events.Add(workflowEvent);
123+
break;
124+
125+
case SuperStepCompletedEvent { CompletionInfo.Checkpoint: { } completedCheckpoint }:
126+
checkpoint = completedCheckpoint;
127+
break;
128+
129+
case MessageActivityEvent activityEvent:
130+
this.Output.WriteLine($"ACTIVITY: {activityEvent.Message}");
131+
events.Add(workflowEvent);
132+
break;
133+
134+
case WorkflowErrorEvent errorEvent:
135+
throw errorEvent.Data as Exception ?? new XunitException("Unexpected failure...");
136+
}
137+
}
138+
139+
return (request, checkpoint);
140+
}
141+
142+
private Workflow CreateWorkflow(string workflowFile)
143+
{
144+
using StreamReader yamlReader = File.OpenText(Path.Combine("Workflows", workflowFile));
145+
DeclarativeWorkflowOptions options = new(new MockAgentProvider().Object) { LoggerFactory = this.Output };
146+
return DeclarativeWorkflowBuilder.Build<string>(yamlReader, options);
147+
}
148+
}
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
kind: Workflow
2+
trigger:
3+
4+
kind: OnConversationStart
5+
id: my_workflow
6+
actions:
7+
8+
- kind: Question
9+
id: question_color
10+
variable: Local.SelectedColor
11+
alwaysPrompt: false
12+
repeatCount: 2
13+
prompt: Please select a color
14+
invalidPrompt: Please pick one of the listed colors.
15+
defaultValue: option-2
16+
defaultValueResponse: No valid color selected, using the default.
17+
entity:
18+
kind: EmbeddedEntity
19+
definition:
20+
kind: ClosedListEntity
21+
items:
22+
- id: option-1
23+
displayName: red
24+
synonyms:
25+
- crimson
26+
- id: option-2
27+
displayName: yello
28+
displayName: Multiple choice
29+
30+
- kind: SendActivity
31+
id: activity_color
32+
activity: |-
33+
Selected: "{Local.SelectedColor}"

0 commit comments

Comments
 (0)