.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/AgentWithMemory/AgentWithMemory_Step01_ChatHistoryMemory/Program.cs

@@ -32,7 +32,7 @@ AIAgent agent = new AzureOpenAIClient(
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
-        Instructions = "You are good at telling jokes.",
+        ChatOptions = new() { Instructions = "You are good at telling jokes." },
         Name = "Joker",
         AIContextProviderFactory = (ctx) => new ChatHistoryMemoryProvider(
             vectorStore,

dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step02_MemoryUsingMem0/Program.cs

@@ -30,7 +30,7 @@ AIAgent agent = new AzureOpenAIClient(
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions()
     {
-        Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details.",
+        ChatOptions = new() { Instructions = "You are a friendly travel assistant. Use known memories about the user when responding, and do not invent details." },
         AIContextProviderFactory = ctx => ctx.SerializedState.ValueKind is not JsonValueKind.Null and not JsonValueKind.Undefined
             // If each thread should have its own Mem0 scope, you can create a new id per thread here:
             // ? new Mem0Provider(mem0HttpClient, new Mem0ProviderScope() { ThreadId = Guid.NewGuid().ToString() })

dotnet/samples/GettingStarted/AgentWithMemory/AgentWithMemory_Step03_CustomMemory/Program.cs

@@ -33,7 +33,7 @@ ChatClient chatClient = new AzureOpenAIClient(
 // 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/AgentWithRAG/AgentWithRAG_Step01_BasicTextRAG/Program.cs

@@ -62,7 +62,7 @@ AIAgent agent = azureOpenAIClient
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
-        Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available.",
+        ChatOptions = new() { Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
         AIContextProviderFactory = ctx => new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)
     });
 

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step02_CustomVectorStoreRAG/Program.cs

@@ -71,7 +71,7 @@ AIAgent agent = azureOpenAIClient
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
-        Instructions = "You are a helpful support specialist for the Microsoft Agent Framework. Answer questions using the provided context and cite the source document when available. Keep responses brief.",
+        ChatOptions = new() { Instructions = "You are a helpful support specialist for the Microsoft Agent Framework. Answer questions using the provided context and cite the source document when available. Keep responses brief." },
         AIContextProviderFactory = ctx => new TextSearchProvider(SearchAdapter, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)
     });
 

dotnet/samples/GettingStarted/AgentWithRAG/AgentWithRAG_Step03_CustomRAGDataSource/Program.cs

@@ -29,7 +29,7 @@ AIAgent agent = new AzureOpenAIClient(
     .GetChatClient(deploymentName)
     .CreateAIAgent(new ChatClientAgentOptions
     {
-        Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available.",
+        ChatOptions = new() { Instructions = "You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available." },
         AIContextProviderFactory = ctx => new TextSearchProvider(MockSearchAsync, ctx.SerializedState, ctx.JsonSerializerOptions, textSearchOptions)
     });
 

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

@@ -22,7 +22,7 @@ ChatClient chatClient = new AzureOpenAIClient(
         .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($"Age: {response.Result.Age}");
 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 @@ AIAgent agent = new AzureOpenAIClient(
     .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 @@ var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT
 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_Step16_ChatReduction/Program.cs

@@ -21,7 +21,7 @@ AIAgent agent = new AzureOpenAIClient(
     .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/FoundryAgents/FoundryAgents_Step05_StructuredOutput/Program.cs

@@ -24,10 +24,12 @@ AIProjectClient aiProjectClient = new(new Uri(endpoint), new AzureCliCredential(
 // Create ChatClientAgent directly
 ChatClientAgent agent = await aiProjectClient.CreateAIAgentAsync(
     model: deploymentName,
-    new ChatClientAgentOptions(name: AssistantName, instructions: AssistantInstructions)
+    new ChatClientAgentOptions()
     {
+        Name = AssistantName,
         ChatOptions = new()
         {
+            Instructions = AssistantInstructions,
             ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<PersonInfo>()
         }
     });
@@ -44,10 +46,12 @@ Console.WriteLine($"Occupation: {response.Result.Occupation}");
 // Create the ChatClientAgent with the specified name, instructions, and expected structured output the agent should produce.
 ChatClientAgent agentWithPersonInfo = aiProjectClient.CreateAIAgent(
     model: deploymentName,
-    new ChatClientAgentOptions(name: AssistantName, instructions: AssistantInstructions)
+    new ChatClientAgentOptions()
     {
+        Name = AssistantName,
         ChatOptions = new()
         {
+            Instructions = AssistantInstructions,
             ResponseFormat = Microsoft.Extensions.AI.ChatResponseFormat.ForJsonSchema<PersonInfo>()
         }
     });

dotnet/samples/GettingStarted/ModelContextProtocol/FoundryAgent_Hosted_MCP/Program.cs

@@ -34,9 +34,9 @@ AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
     options: new()
     {
         Name = "MicrosoftLearnAgent",
-        Instructions = "You answer questions by searching the Microsoft Learn content only.",
         ChatOptions = new()
         {
+            Instructions = "You answer questions by searching the Microsoft Learn content only.",
             Tools = [mcpTool]
         },
     });
@@ -67,9 +67,9 @@ AIAgent agentWithRequiredApproval = await persistentAgentsClient.CreateAIAgentAs
     options: new()
     {
         Name = "MicrosoftLearnAgentWithApproval",
-        Instructions = "You answer questions by searching the Microsoft Learn content only.",
         ChatOptions = new()
         {
+            Instructions = "You answer questions by searching the Microsoft Learn content only.",
             Tools = [mcpToolWithApproval]
         },
     });

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>()
             }
         });