.Net Agents - Magentic Agent Orchestration

dotnet/SK-dotnet.sln

@@ -552,6 +552,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "VectorData.UnitTests", "src
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Agents.Orchestration", "src\Agents\Orchestration\Agents.Orchestration.csproj", "{D1A02387-FA60-22F8-C2ED-4676568B6CC3}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Agents.Magentic", "src\Agents\Magentic\Agents.Magentic.csproj", "{38059FCB-2CD7-C0DE-AE71-DA4D0245ECC7}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -1519,6 +1521,12 @@ Global
 		{D1A02387-FA60-22F8-C2ED-4676568B6CC3}.Publish|Any CPU.Build.0 = Publish|Any CPU
 		{D1A02387-FA60-22F8-C2ED-4676568B6CC3}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{D1A02387-FA60-22F8-C2ED-4676568B6CC3}.Release|Any CPU.Build.0 = Release|Any CPU
+		{38059FCB-2CD7-C0DE-AE71-DA4D0245ECC7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{38059FCB-2CD7-C0DE-AE71-DA4D0245ECC7}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{38059FCB-2CD7-C0DE-AE71-DA4D0245ECC7}.Publish|Any CPU.ActiveCfg = Publish|Any CPU
+		{38059FCB-2CD7-C0DE-AE71-DA4D0245ECC7}.Publish|Any CPU.Build.0 = Publish|Any CPU
+		{38059FCB-2CD7-C0DE-AE71-DA4D0245ECC7}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{38059FCB-2CD7-C0DE-AE71-DA4D0245ECC7}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -1725,6 +1733,7 @@ Global
 		{DA6B4ED4-ED0B-D25C-889C-9F940E714891} = {A70ED5A7-F8E1-4A57-9455-3C05989542DA}
 		{AAC7B5E8-CC4E-49D0-AF6A-2B4F7B43BD84} = {5A7028A7-4DDF-4E4F-84A9-37CE8F8D7E89}
 		{D1A02387-FA60-22F8-C2ED-4676568B6CC3} = {6823CD5E-2ABE-41EB-B865-F86EC13F0CF9}
+		{38059FCB-2CD7-C0DE-AE71-DA4D0245ECC7} = {6823CD5E-2ABE-41EB-B865-F86EC13F0CF9}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {FBDC56A3-86AD-4323-AA0F-201E59123B83}

dotnet/samples/GettingStartedWithAgents/GettingStartedWithAgents.csproj

@@ -47,6 +47,7 @@
     <ProjectReference Include="..\..\src\Agents\OpenAI\Agents.OpenAI.csproj" />
     <ProjectReference Include="..\..\src\Agents\Bedrock\Agents.Bedrock.csproj" />
     <ProjectReference Include="..\..\src\Agents\Orchestration\Agents.Orchestration.csproj" />
+    <ProjectReference Include="..\..\src\Agents\Magentic\Agents.Magentic.csproj" />
     <ProjectReference Include="..\..\src\Agents\Runtime\InProcess\Runtime.InProcess.csproj" />
     <ProjectReference Include="..\..\src\Agents\Yaml\Agents.Yaml.csproj" />
     <ProjectReference Include="..\..\src\Connectors\Connectors.AzureOpenAI\Connectors.AzureOpenAI.csproj" />

dotnet/samples/GettingStartedWithAgents/Orchestration/Step05_Magentic.cs

@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Azure.Identity;
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+using Microsoft.SemanticKernel.Agents.AzureAI;
+using Microsoft.SemanticKernel.Agents.Magentic;
+using Microsoft.SemanticKernel.Agents.Orchestration;
+using Microsoft.SemanticKernel.Agents.Runtime.InProcess;
+using Microsoft.SemanticKernel.ChatCompletion;
+using Microsoft.SemanticKernel.Connectors.OpenAI;
+using AAIP = Azure.AI.Projects;
+
+namespace GettingStarted.Orchestration;
+
+/// <summary>
+/// Demonstrates how to use the <see cref="MagenticOrchestration"/> with two agents:
+/// - A Research agent that can perform web searches
+/// - A Coder agent that can run code using the code interpreter
+/// </summary>
+public class Step05_Magentic(ITestOutputHelper output) : BaseOrchestrationTest(output)
+{
+    private const string ManagerModel = "o3-mini";
+    private const string ResearcherModel = "gpt-4o-search-preview";
+
+    /// <summary>
+    /// Require OpenAI services in order to use "gpt-4o-search-preview" model
+    /// </summary>
+    protected override bool ForceOpenAI => true;
+
+    [Fact]
+    public async Task MagenticTaskAsync()
+    {
+        // Define the agents
+        Kernel researchKernel = CreateKernelWithOpenAIChatCompletion(ResearcherModel);
+        ChatCompletionAgent researchAgent =
+            this.CreateAgent(
+                name: "ResearchAgent",
+                description: "A helpful assistant with access to web search. Ask it to perform web searches.",
+                instructions: "You are a Researcher. You find information without additional computation or quantitative analysis.",
+                kernel: researchKernel);
+
+        AAIP.AIProjectClient projectClient = AzureAIAgent.CreateAzureAIClient(TestConfiguration.AzureAI.ConnectionString, new AzureCliCredential());
+        AAIP.AgentsClient agentsClient = projectClient.GetAgentsClient();
+        AAIP.Agent definition =
+            await agentsClient.CreateAgentAsync(
+                TestConfiguration.AzureAI.ChatModelId,
+                name: "CoderAgent",
+                description: "Write and executes code to process and analyze data.",
+                instructions: "You solve questions using code. Please provide detailed analysis and computation process.",
+                tools: [new Azure.AI.Projects.CodeInterpreterToolDefinition()]);
+        AzureAIAgent coderAgent = new(definition, agentsClient);
+
+        // Define the orchestration
+        OrchestrationMonitor monitor = new();
+        Kernel managerKernel = this.CreateKernelWithChatCompletion(ManagerModel);
+        StandardMagenticManager manager =
+            new(managerKernel.GetRequiredService<IChatCompletionService>(), new OpenAIPromptExecutionSettings())
+            {
+                MaximumInvocationCount = 5,
+            };
+        MagenticOrchestration orchestration =
+            new(manager, researchAgent, coderAgent)
+            {
+                ResponseCallback = monitor.ResponseCallback,
+                LoggerFactory = this.LoggerFactory,
+            };
+
+        // Start the runtime
+        InProcessRuntime runtime = new();
+        await runtime.StartAsync();
+
+        string input =
+            """
+            I am preparing a report on the energy efficiency of different machine learning model architectures.
+            Compare the estimated training and inference energy consumption of ResNet-50, BERT-base, and GPT-2 on standard datasets
+            (e.g., ImageNet for ResNet, GLUE for BERT, WebText for GPT-2).
+            Then, estimate the CO2 emissions associated with each, assuming training on an Azure Standard_NC6s_v3 VM for 24 hours.
+            Provide tables for clarity, and recommend the most energy-efficient model per task type
+            (image classification, text classification, and text generation).
+            """;
+        Console.WriteLine($"\n# INPUT:\n{input}\n");
+        OrchestrationResult<string> result = await orchestration.InvokeAsync(input, runtime);
+        string text = await result.GetValueAsync(TimeSpan.FromSeconds(ResultTimeoutInSeconds * 10));
+        Console.WriteLine($"\n# RESULT: {text}");
+
+        await runtime.RunUntilIdleAsync();
+
+        Console.WriteLine("\n\nORCHESTRATION HISTORY");
+        foreach (ChatMessageContent message in monitor.History)
+        {
+            this.WriteAgentChatMessage(message);
+        }
+    }
+
+    private Kernel CreateKernelWithOpenAIChatCompletion(string model)
+    {
+        IKernelBuilder builder = Kernel.CreateBuilder();
+
+        builder.AddOpenAIChatCompletion(
+            model,
+            TestConfiguration.OpenAI.ApiKey);
+
+        return builder.Build();
+    }
+}

dotnet/src/Agents/AzureAI/Extensions/AgentToolDefinitionExtensions.cs

@@ -242,7 +242,7 @@ private static List<ToolConnection> GetToolConnections(this AgentToolDefinition
 
         var toolConnections = agentToolDefinition.GetRequiredOption<List<object>>("tool_connections");
 
-        return toolConnections.Select(connectionId => new ToolConnection(connectionId.ToString())).ToList();
+        return [.. toolConnections.Select(connectionId => new ToolConnection(connectionId.ToString()))];
     }
 
     private static T GetRequiredOption<T>(this AgentToolDefinition agentToolDefinition, string key)

dotnet/src/Agents/Magentic/Agents.Magentic.csproj

@@ -0,0 +1,36 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <!-- THIS PROPERTY GROUP MUST COME FIRST -->
+    <AssemblyName>Microsoft.SemanticKernel.Agents.Magentic</AssemblyName>
+    <RootNamespace>Microsoft.SemanticKernel.Agents.Magentic</RootNamespace>
+    <TargetFrameworks>net8.0;netstandard2.0</TargetFrameworks> 
+    <NoWarn>$(NoWarn);IDE1006;SKEXP0110;SKEXP0001</NoWarn>
+    <EnablePackageValidation>false</EnablePackageValidation>
+    <VersionSuffix>preview</VersionSuffix>
+  </PropertyGroup>
+
+  <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
+
+  <PropertyGroup>
+    <!-- NuGet Package Settings -->
+    <Title>Semantic Kernel Agents - Magentic Agents</Title>
+    <Description>Defines Magentic agents and orchestration.</Description>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Compile Include="$(RepoRoot)/dotnet/src/InternalUtilities/src/Diagnostics/*" Link="%(RecursiveDir)Utilities/%(Filename)%(Extension)" />
+    <Compile Include="$(RepoRoot)/dotnet/src/InternalUtilities/src/System/*" Link="%(RecursiveDir)Utilities/%(Filename)%(Extension)" />
+    <Compile Include="$(RepoRoot)/dotnet/src/InternalUtilities/agents/Extensions/AgentExtensions.cs" Link="%(RecursiveDir)Utilities/%(Filename)%(Extension)" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Orchestration\Agents.Orchestration.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <InternalsVisibleTo Include="SemanticKernel.Agents.UnitTests" />
+    <InternalsVisibleTo Include="DynamicProxyGenAssembly2" />
+  </ItemGroup>
+
+</Project>

dotnet/src/Agents/Magentic/Internal/PromptExecutionSettingsExtensions.cs

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Reflection;
+
+namespace Microsoft.SemanticKernel.Agents.Magentic.Internal;
+
+/// <summary>
+/// Extension methods for <see cref="PromptExecutionSettings"/> to support response format operations.
+/// </summary>
+public static class PromptExecutionSettingsExtensions
+{
+    private const string ResponseFormatPropertyName = "ResponseFormat";
+
+    /// <summary>
+    /// Determines whether the <paramref name="settings"/> object supports a "ResponseFormat" property of type <see cref="object"/>.
+    /// </summary>
+    /// <param name="settings">The <see cref="PromptExecutionSettings"/> instance to check.</param>
+    /// <returns><c>true</c> if the "ResponseFormat" property exists and is of type <see cref="object"/>; otherwise, <c>false</c>.</returns>
+    public static bool SupportsResponseFormat(this PromptExecutionSettings settings)
+    {
+        Type settingsType = settings.GetType();
+        PropertyInfo? property = settingsType.GetProperty(ResponseFormatPropertyName);
+        return property != null && property.PropertyType == typeof(object);
+    }
+
+    /// <summary>
+    /// Sets the "ResponseFormat" property of the <paramref name="settings"/> object to the specified response type.
+    /// </summary>
+    /// <typeparam name="TResponse">The type to set as the response format.</typeparam>
+    /// <param name="settings">The <see cref="PromptExecutionSettings"/> instance to update.</param>
+    public static void SetResponseFormat<TResponse>(this PromptExecutionSettings settings)
+    {
+        Type settingsType = settings.GetType();
+        PropertyInfo? property = settingsType.GetProperty(ResponseFormatPropertyName);
+        property?.SetValue(settings, typeof(TResponse));
+    }
+}

dotnet/src/Agents/Magentic/Logging/MagenticOrchestrationLogMessages.cs

@@ -0,0 +1,158 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.Logging;
+using Microsoft.SemanticKernel.Agents.Orchestration;
+using Microsoft.SemanticKernel.Agents.Runtime;
+
+namespace Microsoft.SemanticKernel.Agents.Magentic;
+
+/// <summary>
+/// Extensions for logging <see cref="MagenticOrchestration{TInput, TOutput}"/>.
+/// </summary>
+/// <remarks>
+/// This extension uses the <see cref="LoggerMessageAttribute"/> to
+/// generate logging code at compile time to achieve optimized code.
+/// </remarks>
+[ExcludeFromCodeCoverage]
+internal static partial class MagenticOrchestrationLogMessages
+{
+    /// <summary>
+    /// Logs pattern actor registration.
+    /// </summary>
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Information,
+        Message = "REGISTER ACTOR {Orchestration} {label}: {AgentType}")]
+    public static partial void LogRegisterActor(
+        this ILogger logger,
+        string orchestration,
+        AgentType agentType,
+        string label);
+
+    /// <summary>
+    /// Logs agent actor registration.
+    /// </summary>
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Information,
+        Message = "REGISTER ACTOR {Orchestration} {label} #{Count}: {AgentType}")]
+    public static partial void LogRegisterActor(
+        this ILogger logger,
+        string orchestration,
+        AgentType agentType,
+        string label,
+        int count);
+
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Trace,
+        Message = "MAGENTIC AGENT invoked [{AgentId}]")]
+    public static partial void LogMagenticAgentInvoke(
+        this ILogger logger,
+        AgentId agentId);
+
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Trace,
+        Message = "MAGENTIC AGENT result [{AgentId}]: {Message}")]
+    public static partial void LogMagenticAgentResult(
+        this ILogger logger,
+        AgentId agentId,
+        string? message);
+
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Debug,
+        Message = "MAGENTIC MANAGER initialized [{AgentId}]")]
+    public static partial void LogMagenticManagerInit(
+        this ILogger logger,
+        AgentId agentId);
+
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Debug,
+        Message = "MAGENTIC MANAGER invoked [{AgentId}]")]
+    public static partial void LogMagenticManagerInvoke(
+        this ILogger logger,
+        AgentId agentId);
+
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Debug,
+        Message = "MAGENTIC MANAGER terminate? [{AgentId}]: {Result} ({Reason})")]
+    public static partial void LogMagenticManagerTerminate(
+        this ILogger logger,
+        AgentId agentId,
+        bool result,
+        string reason);
+
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Debug,
+        Message = "MAGENTIC MANAGER select: {NextAgent} [{AgentId}]")]
+    public static partial void LogMagenticManagerSelect(
+        this ILogger logger,
+        AgentId agentId,
+        AgentType nextAgent);
+
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Debug,
+        Message = "MAGENTIC MANAGER result [{AgentId}]: '{Result}' ({Reason})")]
+    public static partial void LogMagenticManagerResult(
+        this ILogger logger,
+        AgentId agentId,
+        string result,
+        string reason);
+
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Debug,
+        Message = "MAGENTIC MANAGER user-input? [{AgentId}]: {Result} ({Reason})")]
+    public static partial void LogMagenticManagerInput(
+        this ILogger logger,
+        AgentId agentId,
+        bool result,
+        string reason);
+
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Trace,
+        Message = "MAGENTIC AGENT user-input [{AgentId}]: {Message}")]
+    public static partial void LogMagenticManagerUserInput(
+        this ILogger logger,
+        AgentId agentId,
+        string? message);
+
+    /// <summary>
+    /// Logs <see cref="OrchestrationResult{TValue}"/> timeout while awaiting the orchestration.
+    /// </summary>
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Error,
+        Message = "MAGENTIC FAILURE: {Topic}")]
+    public static partial void LogMagenticManagerStatusFailure(this ILogger logger, TopicId topic, Exception exception);
+
+    /// <summary>
+    /// Logs <see cref="OrchestrationResult{TValue}"/> timeout while awaiting the orchestration.
+    /// </summary>
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Error,
+        Message = "MAGENTIC MANAGER FAILURE: {Topic}")]
+    public static partial void LogMagenticManagerTaskFailed(this ILogger logger, TopicId topic);
+
+    /// <summary>
+    /// Logs <see cref="OrchestrationResult{TValue}"/> timeout while awaiting the orchestration.
+    /// </summary>
+    [LoggerMessage(
+        EventId = 0,
+        Level = LogLevel.Error,
+        Message = "MAGENTIC MANAGER RESET: #{ResetCount} - {Topic}")]
+    public static partial void LogMagenticManagerTaskReset(
+        this ILogger logger,
+        TopicId topic,
+        int resetCount);
+}