test

dotnet/samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/CustomAgentExecutors.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/Workflows/Agents/CustomAgentExecutors/Program.cs

@@ -0,0 +1,240 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowCustomAgentExecutorsSample;
+
+/// <summary>
+/// This sample demonstrates how to create custom executors for AI agents.
+/// This is useful when you want more control over the agent's behaviors in a workflow.
+///
+/// In this example, we create two custom executors:
+/// 1. SloganWriterExecutor: An AI agent that generates slogans based on a given task.
+/// 2. FeedbackExecutor: An AI agent that provides feedback on the generated slogans.
+/// (These two executors manage the agent instances and their conversation threads.)
+///
+/// The workflow alternates between these two executors until the slogan meets a certain
+/// quality threshold or a maximum number of attempts is reached.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - An Azure OpenAI chat completion deployment that supports structured outputs must be configured.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Set up the Azure OpenAI client
+        var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+        var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+        var chatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential()).GetChatClient(deploymentName).AsIChatClient();
+
+        // Create the executors
+        var sloganWriter = new SloganWriterExecutor("SloganWriter", chatClient);
+        var feedbackProvider = new FeedbackExecutor("FeedbackProvider", chatClient);
+
+        // Build the workflow by adding executors and connecting them
+        var workflow = new WorkflowBuilder(sloganWriter)
+            .AddEdge(sloganWriter, feedbackProvider)
+            .AddEdge(feedbackProvider, sloganWriter)
+            .WithOutputFrom(feedbackProvider)
+            .Build();
+
+        // Execute the workflow
+        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, input: "Create a slogan for a new electric SUV that is affordable and fun to drive.");
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            if (evt is SloganGeneratedEvent or FeedbackEvent)
+            {
+                // Custom events to allow us to monitor the progress of the workflow.
+                Console.WriteLine($"{evt}");
+            }
+
+            if (evt is WorkflowOutputEvent outputEvent)
+            {
+                Console.WriteLine($"{outputEvent}");
+            }
+        }
+    }
+}
+
+/// <summary>
+/// A class representing the output of the slogan writer agent.
+/// </summary>
+public sealed class SloganResult
+{
+    [JsonPropertyName("task")]
+    public required string Task { get; set; }
+
+    [JsonPropertyName("slogan")]
+    public required string Slogan { get; set; }
+}
+
+/// <summary>
+/// A class representing the output of the feedback agent.
+/// </summary>
+public sealed class FeedbackResult
+{
+    [JsonPropertyName("comments")]
+    public string Comments { get; set; } = string.Empty;
+
+    [JsonPropertyName("rating")]
+    public int Rating { get; set; }
+
+    [JsonPropertyName("actions")]
+    public string Actions { get; set; } = string.Empty;
+}
+
+/// <summary>
+/// A custom event to indicate that a slogan has been generated.
+/// </summary>
+internal sealed class SloganGeneratedEvent(SloganResult sloganResult) : WorkflowEvent(sloganResult)
+{
+    public override string ToString() => $"Slogan: {sloganResult.Slogan}";
+}
+
+/// <summary>
+/// A custom executor that uses an AI agent to generate slogans based on a given task.
+/// Note that this executor has two message handlers:
+/// 1. HandleAsync(string message): Handles the initial task to create a slogan.
+/// 2. HandleAsync(Feedback message): Handles feedback to improve the slogan.
+/// </summary>
+internal sealed class SloganWriterExecutor : Executor
+{
+    private readonly AIAgent _agent;
+    private AgentThread? _thread;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SloganWriterExecutor"/> class.
+    /// </summary>
+    /// <param name="id">A unique identifier for the executor.</param>
+    /// <param name="chatClient">The chat client to use for the AI agent.</param>
+    public SloganWriterExecutor(string id, IChatClient chatClient) : base(id)
+    {
+        ChatClientAgentOptions agentOptions = new()
+        {
+            ChatOptions = new()
+            {
+                Instructions = "You are a professional slogan writer. You will be given a task to create a slogan.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<SloganResult>()
+            }
+        };
+
+        this._agent = new ChatClientAgent(chatClient, agentOptions);
+    }
+
+    protected override RouteBuilder ConfigureRoutes(RouteBuilder routeBuilder) =>
+        routeBuilder.AddHandler<string, SloganResult>(this.HandleAsync)
+                    .AddHandler<FeedbackResult, SloganResult>(this.HandleAsync);
+
+    public async ValueTask<SloganResult> HandleAsync(string message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._thread ??= await this._agent.GetNewThreadAsync(cancellationToken);
+
+        var result = await this._agent.RunAsync(message, this._thread, cancellationToken: cancellationToken);
+
+        var sloganResult = JsonSerializer.Deserialize<SloganResult>(result.Text) ?? throw new InvalidOperationException("Failed to deserialize slogan result.");
+
+        await context.AddEventAsync(new SloganGeneratedEvent(sloganResult), cancellationToken);
+        return sloganResult;
+    }
+
+    public async ValueTask<SloganResult> HandleAsync(FeedbackResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        var feedbackMessage = $"""
+            Here is the feedback on your previous slogan:
+            Comments: {message.Comments}
+            Rating: {message.Rating}
+            Suggested Actions: {message.Actions}
+
+            Please use this feedback to improve your slogan.
+            """;
+
+        var result = await this._agent.RunAsync(feedbackMessage, this._thread, cancellationToken: cancellationToken);
+        var sloganResult = JsonSerializer.Deserialize<SloganResult>(result.Text) ?? throw new InvalidOperationException("Failed to deserialize slogan result.");
+
+        await context.AddEventAsync(new SloganGeneratedEvent(sloganResult), cancellationToken);
+        return sloganResult;
+    }
+}
+
+/// <summary>
+/// A custom event to indicate that feedback has been provided.
+/// </summary>
+internal sealed class FeedbackEvent(FeedbackResult feedbackResult) : WorkflowEvent(feedbackResult)
+{
+    private readonly JsonSerializerOptions _options = new() { WriteIndented = true };
+    public override string ToString() => $"Feedback:\n{JsonSerializer.Serialize(feedbackResult, this._options)}";
+}
+
+/// <summary>
+/// A custom executor that uses an AI agent to provide feedback on a slogan.
+/// </summary>
+internal sealed class FeedbackExecutor : Executor<SloganResult>
+{
+    private readonly AIAgent _agent;
+    private AgentThread? _thread;
+
+    public int MinimumRating { get; init; } = 8;
+
+    public int MaxAttempts { get; init; } = 3;
+
+    private int _attempts;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FeedbackExecutor"/> class.
+    /// </summary>
+    /// <param name="id">A unique identifier for the executor.</param>
+    /// <param name="chatClient">The chat client to use for the AI agent.</param>
+    public FeedbackExecutor(string id, IChatClient chatClient) : base(id)
+    {
+        ChatClientAgentOptions agentOptions = new()
+        {
+            ChatOptions = new()
+            {
+                Instructions = "You are a professional editor. You will be given a slogan and the task it is meant to accomplish.",
+                ResponseFormat = ChatResponseFormat.ForJsonSchema<FeedbackResult>()
+            }
+        };
+
+        this._agent = new ChatClientAgent(chatClient, agentOptions);
+    }
+
+    public override async ValueTask HandleAsync(SloganResult message, IWorkflowContext context, CancellationToken cancellationToken = default)
+    {
+        this._thread ??= await this._agent.GetNewThreadAsync(cancellationToken);
+
+        var sloganMessage = $"""
+            Here is a slogan for the task '{message.Task}':
+            Slogan: {message.Slogan}
+            Please provide feedback on this slogan, including comments, a rating from 1 to 10, and suggested actions for improvement.
+            """;
+
+        var response = await this._agent.RunAsync(sloganMessage, this._thread, cancellationToken: cancellationToken);
+        var feedback = JsonSerializer.Deserialize<FeedbackResult>(response.Text) ?? throw new InvalidOperationException("Failed to deserialize feedback.");
+
+        await context.AddEventAsync(new FeedbackEvent(feedback), cancellationToken);
+
+        if (feedback.Rating >= this.MinimumRating)
+        {
+            await context.YieldOutputAsync($"The following slogan was accepted:\n\n{message.Slogan}", cancellationToken);
+            return;
+        }
+
+        if (this._attempts >= this.MaxAttempts)
+        {
+            await context.YieldOutputAsync($"The slogan was rejected after {this.MaxAttempts} attempts. Final slogan:\n\n{message.Slogan}", cancellationToken);
+            return;
+        }
+
+        await context.SendMessageAsync(feedback, cancellationToken: cancellationToken);
+        this._attempts++;
+    }
+}

dotnet/samples/GettingStarted/Workflows/Agents/FoundryAgent/FoundryAgent.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.Agents.Persistent" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.AzureAI.Persistent\Microsoft.Agents.AI.AzureAI.Persistent.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/Workflows/Agents/FoundryAgent/Program.cs

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.Agents.Persistent;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowFoundryAgentSample;
+
+/// <summary>
+/// This sample shows how to use Azure Foundry Agents within a workflow.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - An Azure Foundry project endpoint and model id.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Set up the Azure OpenAI client
+        var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_ENDPOINT")
+            ?? throw new InvalidOperationException("AZURE_FOUNDRY_PROJECT_ENDPOINT is not set.");
+        var deploymentName = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_PROJECT_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+        var persistentAgentsClient = new PersistentAgentsClient(endpoint, new AzureCliCredential());
+
+        // Create agents
+        AIAgent frenchAgent = await GetTranslationAgentAsync("French", persistentAgentsClient, deploymentName);
+        AIAgent spanishAgent = await GetTranslationAgentAsync("Spanish", persistentAgentsClient, deploymentName);
+        AIAgent englishAgent = await GetTranslationAgentAsync("English", persistentAgentsClient, deploymentName);
+
+        // Build the workflow by adding executors and connecting them
+        var workflow = new WorkflowBuilder(frenchAgent)
+            .AddEdge(frenchAgent, spanishAgent)
+            .AddEdge(spanishAgent, englishAgent)
+            .Build();
+
+        // Execute the workflow
+        await using StreamingRun run = await InProcessExecution.StreamAsync(workflow, new ChatMessage(ChatRole.User, "Hello World!"));
+        // Must send the turn token to trigger the agents.
+        // The agents are wrapped as executors. When they receive messages,
+        // they will cache the messages and only start processing when they receive a TurnToken.
+        await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+        await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+        {
+            if (evt is AgentResponseUpdateEvent executorComplete)
+            {
+                Console.WriteLine($"{executorComplete.ExecutorId}: {executorComplete.Data}");
+            }
+        }
+
+        // Cleanup the agents created for the sample.
+        await persistentAgentsClient.Administration.DeleteAgentAsync(frenchAgent.Id);
+        await persistentAgentsClient.Administration.DeleteAgentAsync(spanishAgent.Id);
+        await persistentAgentsClient.Administration.DeleteAgentAsync(englishAgent.Id);
+    }
+
+    /// <summary>
+    /// Creates a translation agent for the specified target language.
+    /// </summary>
+    /// <param name="targetLanguage">The target language for translation</param>
+    /// <param name="persistentAgentsClient">The PersistentAgentsClient to create the agent</param>
+    /// <param name="model">The model to use for the agent</param>
+    /// <returns>A ChatClientAgent configured for the specified language</returns>
+    private static async Task<ChatClientAgent> GetTranslationAgentAsync(
+        string targetLanguage,
+        PersistentAgentsClient persistentAgentsClient,
+        string model)
+    {
+        var agentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
+            model: model,
+            name: $"{targetLanguage} Translator",
+            instructions: $"You are a translation assistant that translates the provided text to {targetLanguage}.");
+
+        return await persistentAgentsClient.GetAIAgentAsync(agentMetadata.Value.Id);
+    }
+}

dotnet/samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/Program.cs

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowAsAnAgentSample;
+
+/// <summary>
+/// This sample introduces the concepts workflows as agents, where a workflow can be
+/// treated as an <see cref="AIAgent"/>. This allows you to interact with a workflow
+/// as if it were a single agent.
+///
+/// In this example, we create a workflow that uses two language agents to process
+/// input concurrently, one that responds in French and another that responds in English.
+///
+/// You will interact with the workflow in an interactive loop, sending messages and receiving
+/// streaming responses from the workflow as if it were an agent who responds in both languages.
+/// </summary>
+/// <remarks>
+/// Pre-requisites:
+/// - Foundational samples should be completed first.
+/// - This sample uses concurrent processing.
+/// - An Azure OpenAI endpoint and deployment name.
+/// </remarks>
+public static class Program
+{
+    private static async Task Main()
+    {
+        // Set up the Azure OpenAI client
+        var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+        var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";
+        var chatClient = new AzureOpenAIClient(new Uri(endpoint), new AzureCliCredential()).GetChatClient(deploymentName).AsIChatClient();
+
+        // Create the workflow and turn it into an agent
+        var workflow = WorkflowFactory.BuildWorkflow(chatClient);
+        var agent = workflow.AsAgent("workflow-agent", "Workflow Agent");
+        var thread = await agent.GetNewThreadAsync();
+
+        // Start an interactive loop to interact with the workflow as if it were an agent
+        while (true)
+        {
+            Console.WriteLine();
+            Console.Write("User (or 'exit' to quit): ");
+            string? input = Console.ReadLine();
+            if (string.IsNullOrWhiteSpace(input) || input.Equals("exit", StringComparison.OrdinalIgnoreCase))
+            {
+                break;
+            }
+
+            await ProcessInputAsync(agent, thread, input);
+        }
+
+        // Helper method to process user input and display streaming responses. To display
+        // multiple interleaved responses correctly, we buffer updates by message ID and
+        // re-render all messages on each update.
+        static async Task ProcessInputAsync(AIAgent agent, AgentThread thread, string input)
+        {
+            Dictionary<string, List<AgentResponseUpdate>> buffer = [];
+            await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(input, thread))
+            {
+                if (update.MessageId is null || string.IsNullOrEmpty(update.Text))
+                {
+                    // skip updates that don't have a message ID or text
+                    continue;
+                }
+                Console.Clear();
+
+                if (!buffer.TryGetValue(update.MessageId, out List<AgentResponseUpdate>? value))
+                {
+                    value = [];
+                    buffer[update.MessageId] = value;
+                }
+                value.Add(update);
+
+                foreach (var (messageId, segments) in buffer)
+                {
+                    string combinedText = string.Concat(segments);
+                    Console.WriteLine($"{segments[0].AuthorName}: {combinedText}");
+                    Console.WriteLine();
+                }
+            }
+        }
+    }
+}

dotnet/samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/WorkflowAsAnAgent.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Workflows\Microsoft.Agents.AI.Workflows.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/GettingStarted/Workflows/Agents/WorkflowAsAnAgent/WorkflowFactory.cs

@@ -0,0 +1,74 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+using Microsoft.Extensions.AI;
+
+namespace WorkflowAsAnAgentSample;
+
+internal static class WorkflowFactory
+{
+    /// <summary>
+    /// Creates a workflow that uses two language agents to process input concurrently.
+    /// </summary>
+    /// <param name="chatClient">The chat client to use for the agents</param>
+    /// <returns>A workflow that processes input using two language agents</returns>
+    internal static Workflow BuildWorkflow(IChatClient chatClient)
+    {
+        // Create executors
+        var startExecutor = new ChatForwardingExecutor("Start");
+        var aggregationExecutor = new ConcurrentAggregationExecutor();
+        AIAgent frenchAgent = GetLanguageAgent("French", chatClient);
+        AIAgent englishAgent = GetLanguageAgent("English", chatClient);
+
+        // Build the workflow by adding executors and connecting them
+        return new WorkflowBuilder(startExecutor)
+            .AddFanOutEdge(startExecutor, [frenchAgent, englishAgent])
+            .AddFanInEdge([frenchAgent, englishAgent], aggregationExecutor)
+            .WithOutputFrom(aggregationExecutor)
+            .Build();
+    }
+
+    /// <summary>
+    /// Creates a language agent for the specified target language.
+    /// </summary>
+    /// <param name="targetLanguage">The target language for translation</param>
+    /// <param name="chatClient">The chat client to use for the agent</param>
+    /// <returns>A ChatClientAgent configured for the specified language</returns>
+    private static ChatClientAgent GetLanguageAgent(string targetLanguage, IChatClient chatClient) =>
+        new(chatClient, instructions: $"You're a helpful assistant who always responds in {targetLanguage}.", name: $"{targetLanguage}Agent");
+
+    /// <summary>
+    /// Executor that aggregates the results from the concurrent agents.
+    /// </summary>
+    private sealed class ConcurrentAggregationExecutor() :
+        Executor<List<ChatMessage>>("ConcurrentAggregationExecutor"), IResettableExecutor
+    {
+        private readonly List<ChatMessage> _messages = [];
+
+        /// <summary>
+        /// Handles incoming messages from the agents and aggregates their responses.
+        /// </summary>
+        /// <param name="message">The messages from the agent</param>
+        /// <param name="context">Workflow context for accessing workflow services and adding events</param>
+        /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.
+        /// The default is <see cref="CancellationToken.None"/>.</param>
+        public override async ValueTask HandleAsync(List<ChatMessage> message, IWorkflowContext context, CancellationToken cancellationToken = default)
+        {
+            this._messages.AddRange(message);
+
+            if (this._messages.Count == 2)
+            {
+                var formattedMessages = string.Join(Environment.NewLine, this._messages.Select(m => $"{m.Text}"));
+                await context.YieldOutputAsync(formattedMessages, cancellationToken);
+            }
+        }
+
+        /// <inheritdoc/>
+        public ValueTask ResetAsync()
+        {
+            this._messages.Clear();
+            return default;
+        }
+    }
+}