.NET [Breaking] Simplify and Refactor ChatclientAgentOptions Ctor + Instructions (#1517)

* Point AgentOptions.Instructions to ChatOptions

* Update tests and checks

* Update xml docs

* Removal of agentOptions.Instructions in favor of chatOptions.Instructions

* Instructions and tool check consistency

* Instructions and tool check consistency

* Address comment

* Update .github/upgrades/prompts/SemanticKernelToAgentFramework.md

Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>

* Address PR Comment

* Update latest changes to comply with the PR proposal

* Address feedback

* Update dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentTests.cs

Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>

* Address instructions

* Update declarative to use promptAgent.Instrucitons with chatOptions.Instructions

---------

Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>
Co-authored-by: Mark Wallace <127216156+markwallace-microsoft@users.noreply.github.com>

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 @@ public static class Program
     /// </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 @@ public static class Program
     /// </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 @@ public static class Program
     /// </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 @@ public static class Program
     /// </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 @@ public static class Program
     /// </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 @@ public static class Program
     /// </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 @@ public static class Program
     /// </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/samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/Program.cs

@@ -285,19 +285,19 @@ internal sealed class CriticExecutor : Executor<ChatMessage, CriticDecision>
         this._agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
         {
             Name = "Critic",
-            Instructions = """
-                You are a constructive critic. Review the content and provide specific feedback.
-                Always try to provide actionable suggestions for improvement and strive to identify improvement points.
-                Only approve if the content is high quality, clear, and meets the original requirements and you see no improvement points.
-                
-                Provide your decision as structured output with:
-                - approved: true if content is good, false if revisions needed
-                - feedback: specific improvements needed (empty if approved)
-                
-                Be concise but specific in your feedback.
-                """,
             ChatOptions = new()
             {
+                Instructions = """
+                    You are a constructive critic. Review the content and provide specific feedback.
+                    Always try to provide actionable suggestions for improvement and strive to identify improvement points.
+                    Only approve if the content is high quality, clear, and meets the original requirements and you see no improvement points.
+                
+                    Provide your decision as structured output with:
+                    - approved: true if content is good, false if revisions needed
+                    - feedback: specific improvements needed (empty if approved)
+                
+                    Be concise but specific in your feedback.
+                    """,
                 ResponseFormat = ChatResponseFormat.ForJsonSchema<CriticDecision>()
             }
         });