.NET [Breaking] Simplify and Refactor ChatclientAgentOptions Ctor + Instructions

dotnet/agent-framework-dotnet.slnx

@@ -131,9 +131,6 @@
     <Project Path="samples/GettingStarted/Workflows/_Foundational/05_MultiModelService/05_MultiModelService.csproj" />
     <Project Path="samples/GettingStarted/Workflows/_Foundational/06_SubWorkflows/06_SubWorkflows.csproj" />
   </Folder>
-  <Folder Name="/Samples/SemanticKernelMigration/">
-    <File Path="samples/SemanticKernelMigration/README.md" />
-  </Folder>
   <Folder Name="/Solution Items/">
     <File Path=".editorconfig" />
     <File Path=".gitignore" />

dotnet/samples/GettingStarted/Agents/Agent_Step05_StructuredOutput/Program.cs

@@ -22,7 +22,7 @@
         .GetChatClient(deploymentName);
 
 // Create the ChatClientAgent with the specified name and instructions.
-ChatClientAgent agent = chatClient.CreateAIAgent(new ChatClientAgentOptions(name: "HelpfulAssistant", instructions: "You are a helpful assistant."));
+ChatClientAgent agent = chatClient.CreateAIAgent(name: "HelpfulAssistant", instructions: "You are a helpful assistant.");
 
 // Set PersonInfo as the type parameter of RunAsync method to specify the expected structured output from the agent and invoke the agent with some unstructured input.
 AgentRunResponse<PersonInfo> response = await agent.RunAsync<PersonInfo>("Please provide information about John Smith, who is a 35-year-old software engineer.");
@@ -34,12 +34,10 @@
 Console.WriteLine($"Occupation: {response.Result.Occupation}");
 
 // Create the ChatClientAgent with the specified name, instructions, and expected structured output the agent should produce.
-ChatClientAgent agentWithPersonInfo = chatClient.CreateAIAgent(new ChatClientAgentOptions(name: "HelpfulAssistant", instructions: "You are a helpful assistant.")
+ChatClientAgent agentWithPersonInfo = chatClient.CreateAIAgent(new ChatClientAgentOptions()
 {
-    ChatOptions = new()
-    {
-        ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<PersonInfo>()
-    }
+    Name = "HelpfulAssistant",
+    ChatOptions = new() { Instructions = "You are a helpful assistant.", ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<PersonInfo>() }
 });
 
 // Invoke the agent with some unstructured input while streaming, to extract the structured information from.

dotnet/samples/GettingStarted/Agents/Agent_Step07_3rdPartyThreadStorage/Program.cs

@@ -28,7 +28,7 @@
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
-        Instructions = "You are good at telling jokes.",
+        ChatOptions = new() { Instructions = "You are good at telling jokes." },
         Name = "Joker",
         ChatMessageStoreFactory = ctx =>
         {

dotnet/samples/GettingStarted/Agents/Agent_Step09_DependencyInjection/Program.cs

@@ -18,8 +18,7 @@
 HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
 
 // Add agent options to the service collection.
-builder.Services.AddSingleton(
-    new ChatClientAgentOptions(instructions: "You are good at telling jokes.", name: "Joker"));
+builder.Services.AddSingleton(new ChatClientAgentOptions() { Name = "Joker", ChatOptions = new() { Instructions = "You are good at telling jokes." } });
 
 // Add a chat client to the service collection.
 builder.Services.AddKeyedChatClient("AzureOpenAI", (sp) => new AzureOpenAIClient(

dotnet/samples/GettingStarted/Agents/Agent_Step13_Memory/Program.cs

@@ -33,7 +33,7 @@
 // and its storage to that user id.
 AIAgent agent = chatClient.CreateAIAgent(new ChatClientAgentOptions()
 {
-    Instructions = "You are a friendly assistant. Always address the user by their name.",
+    ChatOptions = new() { Instructions = "You are a friendly assistant. Always address the user by their name." },
     AIContextProviderFactory = ctx => new UserInfoMemory(chatClient.AsIChatClient(), ctx.SerializedState, ctx.JsonSerializerOptions)
 });
 

dotnet/samples/GettingStarted/Agents/Agent_Step16_ChatReduction/Program.cs

@@ -21,7 +21,7 @@
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
-        Instructions = "You are good at telling jokes.",
+        ChatOptions = new() { Instructions = "You are good at telling jokes." },
         Name = "Joker",
         ChatMessageStoreFactory = ctx => new InMemoryChatMessageStore(new MessageCountingChatReducer(2), ctx.SerializedState, ctx.JsonSerializerOptions)
     });

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

@@ -118,10 +118,11 @@ internal sealed class SloganWriterExecutor : Executor
     /// <param name="chatClient">The chat client to use for the AI agent.</param>
     public SloganWriterExecutor(string id, IChatClient chatClient) : base(id)
     {
-        ChatClientAgentOptions agentOptions = new(instructions: "You are a professional slogan writer. You will be given a task to create a slogan.")
+        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>()
             }
         };
@@ -193,10 +194,11 @@ internal sealed class FeedbackExecutor : Executor<SloganResult>
     /// <param name="chatClient">The chat client to use for the AI agent.</param>
     public FeedbackExecutor(string id, IChatClient chatClient) : base(id)
     {
-        ChatClientAgentOptions agentOptions = new(instructions: "You are a professional editor. You will be given a slogan and the task it is meant to accomplish.")
+        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>()
             }
         };

dotnet/samples/GettingStarted/Workflows/ConditionalEdges/01_EdgeCondition/Program.cs

@@ -85,10 +85,11 @@ private static async Task Main()
     /// </summary>
     /// <returns>A ChatClientAgent configured for spam detection</returns>
     private static ChatClientAgent GetSpamDetectionAgent(IChatClient chatClient) =>
-        new(chatClient, new ChatClientAgentOptions(instructions: "You are a spam detection assistant that identifies spam emails.")
+        new(chatClient, new ChatClientAgentOptions()
         {
             ChatOptions = new()
             {
+                Instructions = "You are a spam detection assistant that identifies spam emails.",
                 ResponseFormat = ChatResponseFormat.ForJsonSchema<DetectionResult>()
             }
         });
@@ -98,10 +99,11 @@ private static ChatClientAgent GetSpamDetectionAgent(IChatClient chatClient) =>
     /// </summary>
     /// <returns>A ChatClientAgent configured for email assistance</returns>
     private static ChatClientAgent GetEmailAssistantAgent(IChatClient chatClient) =>
-        new(chatClient, new ChatClientAgentOptions(instructions: "You are an email assistant that helps users draft responses to emails with professionalism.")
+        new(chatClient, new ChatClientAgentOptions()
         {
             ChatOptions = new()
             {
+                Instructions = "You are an email assistant that helps users draft responses to emails with professionalism.",
                 ResponseFormat = ChatResponseFormat.ForJsonSchema<EmailResponse>()
             }
         });

dotnet/samples/GettingStarted/Workflows/ConditionalEdges/02_SwitchCase/Program.cs

@@ -100,10 +100,11 @@ private static async Task Main()
     /// </summary>
     /// <returns>A ChatClientAgent configured for spam detection</returns>
     private static ChatClientAgent GetSpamDetectionAgent(IChatClient chatClient) =>
-        new(chatClient, new ChatClientAgentOptions(instructions: "You are a spam detection assistant that identifies spam emails. Be less confident in your assessments.")
+        new(chatClient, new ChatClientAgentOptions()
         {
             ChatOptions = new()
             {
+                Instructions = "You are a spam detection assistant that identifies spam emails. Be less confident in your assessments.",
                 ResponseFormat = ChatResponseFormat.ForJsonSchema<DetectionResult>()
             }
         });
@@ -113,10 +114,11 @@ private static ChatClientAgent GetSpamDetectionAgent(IChatClient chatClient) =>
     /// </summary>
     /// <returns>A ChatClientAgent configured for email assistance</returns>
     private static ChatClientAgent GetEmailAssistantAgent(IChatClient chatClient) =>
-        new(chatClient, new ChatClientAgentOptions(instructions: "You are an email assistant that helps users draft responses to emails with professionalism.")
+        new(chatClient, new ChatClientAgentOptions()
         {
             ChatOptions = new()
             {
+                Instructions = "You are an email assistant that helps users draft responses to emails with professionalism.",
                 ResponseFormat = ChatResponseFormat.ForJsonSchema<EmailResponse>()
             }
         });

dotnet/samples/GettingStarted/Workflows/ConditionalEdges/03_MultiSelection/Program.cs

@@ -140,10 +140,11 @@ private static async Task Main()
     /// </summary>
     /// <returns>A ChatClientAgent configured for email analysis</returns>
     private static ChatClientAgent GetEmailAnalysisAgent(IChatClient chatClient) =>
-        new(chatClient, new ChatClientAgentOptions(instructions: "You are a spam detection assistant that identifies spam emails.")
+        new(chatClient, new ChatClientAgentOptions()
         {
             ChatOptions = new()
             {
+                Instructions = "You are a spam detection assistant that identifies spam emails.",
                 ResponseFormat = ChatResponseFormat.ForJsonSchema<AnalysisResult>()
             }
         });
@@ -153,10 +154,11 @@ private static ChatClientAgent GetEmailAnalysisAgent(IChatClient chatClient) =>
     /// </summary>
     /// <returns>A ChatClientAgent configured for email assistance</returns>
     private static ChatClientAgent GetEmailAssistantAgent(IChatClient chatClient) =>
-        new(chatClient, new ChatClientAgentOptions(instructions: "You are an email assistant that helps users draft responses to emails with professionalism.")
+        new(chatClient, new ChatClientAgentOptions()
         {
             ChatOptions = new()
             {
+                Instructions = "You are an email assistant that helps users draft responses to emails with professionalism.",
                 ResponseFormat = ChatResponseFormat.ForJsonSchema<EmailResponse>()
             }
         });
@@ -166,10 +168,11 @@ private static ChatClientAgent GetEmailAssistantAgent(IChatClient chatClient) =>
     /// </summary>
     /// <returns>A ChatClientAgent configured for email summarization</returns>
     private static ChatClientAgent GetEmailSummaryAgent(IChatClient chatClient) =>
-        new(chatClient, new ChatClientAgentOptions(instructions: "You are an assistant that helps users summarize emails.")
+        new(chatClient, new ChatClientAgentOptions()
         {
             ChatOptions = new()
             {
+                Instructions = "You are an assistant that helps users summarize emails.",
                 ResponseFormat = ChatResponseFormat.ForJsonSchema<EmailSummary>()
             }
         });

dotnet/src/Microsoft.Agents.AI.AzureAI/PersistentAgentsClientExtensions.cs

@@ -55,12 +55,17 @@ public static ChatClientAgent GetAIAgent(this PersistentAgentsClient persistentA
             chatClient = clientFactory(chatClient);
         }
 
+        if (!string.IsNullOrWhiteSpace(persistentAgentMetadata.Instructions) && chatOptions?.Instructions is null)
+        {
+            chatOptions ??= new ChatOptions();
+            chatOptions.Instructions = persistentAgentMetadata.Instructions;
+        }
+
         return new ChatClientAgent(chatClient, options: new()
         {
             Id = persistentAgentMetadata.Id,
             Name = persistentAgentMetadata.Name,
             Description = persistentAgentMetadata.Description,
-            Instructions = persistentAgentMetadata.Instructions,
             ChatOptions = chatOptions
         });
     }
@@ -179,12 +184,17 @@ public static ChatClientAgent GetAIAgent(this PersistentAgentsClient persistentA
             chatClient = clientFactory(chatClient);
         }
 
+        if (!string.IsNullOrWhiteSpace(persistentAgentMetadata.Instructions) && options.ChatOptions?.Instructions is null)
+        {
+            options.ChatOptions ??= new ChatOptions();
+            options.ChatOptions.Instructions = persistentAgentMetadata.Instructions;
+        }
+
         var agentOptions = new ChatClientAgentOptions()
         {
             Id = persistentAgentMetadata.Id,
             Name = options.Name ?? persistentAgentMetadata.Name,
             Description = options.Description ?? persistentAgentMetadata.Description,
-            Instructions = options.Instructions ?? persistentAgentMetadata.Instructions,
             ChatOptions = options.ChatOptions,
             AIContextProviderFactory = options.AIContextProviderFactory,
             ChatMessageStoreFactory = options.ChatMessageStoreFactory,
@@ -415,7 +425,7 @@ public static ChatClientAgent CreateAIAgent(
             model: model,
             name: options.Name,
             description: options.Description,
-            instructions: options.Instructions,
+            instructions: options.ChatOptions?.Instructions,
             tools: toolDefinitionsAndResources.ToolDefinitions,
             toolResources: toolDefinitionsAndResources.ToolResources,
             temperature: null,
@@ -473,7 +483,7 @@ public static async Task<ChatClientAgent> CreateAIAgentAsync(
             model: model,
             name: options.Name,
             description: options.Description,
-            instructions: options.Instructions,
+            instructions: options.ChatOptions?.Instructions,
             tools: toolDefinitionsAndResources.ToolDefinitions,
             toolResources: toolDefinitionsAndResources.ToolResources,
             temperature: null,

dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIAssistantClientExtensions.cs

@@ -73,12 +73,17 @@ public static ChatClientAgent GetAIAgent(
             chatClient = clientFactory(chatClient);
         }
 
+        if (!string.IsNullOrWhiteSpace(assistantMetadata.Instructions) && chatOptions?.Instructions is null)
+        {
+            chatOptions ??= new ChatOptions();
+            chatOptions.Instructions = assistantMetadata.Instructions;
+        }
+
         return new ChatClientAgent(chatClient, options: new()
         {
             Id = assistantMetadata.Id,
             Name = assistantMetadata.Name,
             Description = assistantMetadata.Description,
-            Instructions = assistantMetadata.Instructions,
             ChatOptions = chatOptions
         });
     }
@@ -203,12 +208,17 @@ public static ChatClientAgent GetAIAgent(
             chatClient = clientFactory(chatClient);
         }
 
+        if (string.IsNullOrWhiteSpace(options.ChatOptions?.Instructions) && !string.IsNullOrWhiteSpace(assistantMetadata.Instructions))
+        {
+            options.ChatOptions ??= new ChatOptions();
+            options.ChatOptions.Instructions = assistantMetadata.Instructions;
+        }
+
         var mergedOptions = new ChatClientAgentOptions()
         {
             Id = assistantMetadata.Id,
             Name = options.Name ?? assistantMetadata.Name,
             Description = options.Description ?? assistantMetadata.Description,
-            Instructions = options.Instructions ?? assistantMetadata.Instructions,
             ChatOptions = options.ChatOptions,
             AIContextProviderFactory = options.AIContextProviderFactory,
             ChatMessageStoreFactory = options.ChatMessageStoreFactory,
@@ -321,10 +331,10 @@ public static ChatClientAgent CreateAIAgent(
             {
                 Name = name,
                 Description = description,
-                Instructions = instructions,
-                ChatOptions = tools is null ? null : new ChatOptions()
+                ChatOptions = tools is null && string.IsNullOrWhiteSpace(instructions) ? null : new ChatOptions()
                 {
                     Tools = tools,
+                    Instructions = instructions
                 }
             },
             clientFactory,
@@ -356,7 +366,7 @@ public static ChatClientAgent CreateAIAgent(
         {
             Name = options.Name,
             Description = options.Description,
-            Instructions = options.Instructions,
+            Instructions = options.ChatOptions?.Instructions,
         };
 
         // Convert AITools to ToolDefinitions and ToolResources
@@ -382,12 +392,7 @@ public static ChatClientAgent CreateAIAgent(
             chatClient = clientFactory(chatClient);
         }
 
-        var agentOptions = options.Clone();
-        agentOptions.Id = assistantId;
-        options.ChatOptions ??= new ChatOptions();
-        options.ChatOptions!.Tools = toolDefinitionsAndResources.FunctionToolsAndOtherTools;
-
-        return new ChatClientAgent(chatClient, agentOptions, loggerFactory);
+        return new ChatClientAgent(chatClient, options, loggerFactory);
     }
 
     /// <summary>
@@ -418,10 +423,10 @@ await client.CreateAIAgentAsync(model,
             {
                 Name = name,
                 Description = description,
-                Instructions = instructions,
-                ChatOptions = tools is null ? null : new ChatOptions()
+                ChatOptions = tools is null && string.IsNullOrWhiteSpace(instructions) ? null : new ChatOptions()
                 {
                     Tools = tools,
+                    Instructions = instructions,
                 }
             },
             clientFactory,
@@ -453,7 +458,7 @@ public static async Task<ChatClientAgent> CreateAIAgentAsync(
         {
             Name = options.Name,
             Description = options.Description,
-            Instructions = options.Instructions,
+            Instructions = options.ChatOptions?.Instructions,
         };
 
         // Convert AITools to ToolDefinitions and ToolResources

dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIChatClientExtensions.cs

@@ -47,9 +47,9 @@ public static ChatClientAgent CreateAIAgent(
             {
                 Name = name,
                 Description = description,
-                Instructions = instructions,
-                ChatOptions = tools is null ? null : new ChatOptions()
+                ChatOptions = tools is null && string.IsNullOrWhiteSpace(instructions) ? null : new ChatOptions()
                 {
+                    Instructions = instructions,
                     Tools = tools,
                 }
             },

dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIResponseClientExtensions.cs

@@ -48,9 +48,9 @@ public static ChatClientAgent CreateAIAgent(
             {
                 Name = name,
                 Description = description,
-                Instructions = instructions,
-                ChatOptions = tools is null ? null : new ChatOptions()
+                ChatOptions = tools is null && string.IsNullOrWhiteSpace(instructions) ? null : new ChatOptions()
                 {
+                    Instructions = instructions,
                     Tools = tools,
                 }
             },

dotnet/src/Microsoft.Agents.AI.OpenAI/OpenAIChatClientAgent.cs

@@ -32,7 +32,7 @@ public OpenAIChatClientAgent(
         {
             Name = name,
             Description = description,
-            Instructions = instructions,
+            ChatOptions = new ChatOptions() { Instructions = instructions },
         }, loggerFactory)
     {
     }

dotnet/src/Microsoft.Agents.AI.OpenAI/OpenAIResponseClientAgent.cs

@@ -32,7 +32,7 @@ public OpenAIResponseClientAgent(
         {
             Name = name,
             Description = description,
-            Instructions = instructions,
+            ChatOptions = new ChatOptions() { Instructions = instructions },
         }, loggerFactory)
     {
     }