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

.github/upgrades/prompts/SemanticKernelToAgentFramework.md

@@ -1636,4 +1636,4 @@ The property mapping guide from a `AutoFunctionInvocationContext` to a `Function
 | Result | Use `return` from the delegate |
 | Terminate | Terminate |
 | CancellationToken | provided via argument to middleware delegate |
-| Arguments | Arguments |
+| Arguments | Arguments |

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

@@ -32,7 +32,7 @@
     .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 @@
     .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 @@
 // 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 @@
     .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 @@
     .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 @@
     .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 @@
         .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_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/FoundryAgents/FoundryAgents_Step05_StructuredOutput/Program.cs

@@ -24,10 +24,12 @@
 // 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 @@
 // 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 @@
     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 @@
     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 @@ 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/samples/GettingStarted/Workflows/_Foundational/08_WriterCriticWorkflow/Program.cs

@@ -285,19 +285,19 @@ public CriticExecutor(IChatClient chatClient) : base("Critic")
         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>()
             }
         });

dotnet/samples/M365Agent/Agents/WeatherForecastAgent.cs

@@ -33,9 +33,9 @@ public WeatherForecastAgent(IChatClient chatClient)
             new ChatClientAgentOptions()
             {
                 Name = AgentName,
-                Instructions = AgentInstructions,
                 ChatOptions = new ChatOptions()
                 {
+                    Instructions = AgentInstructions,
                     Tools = [new ApprovalRequiredAIFunction(AIFunctionFactory.Create(GetWeather))],
                     // We want the agent to return structured output in a known format
                     // so that we can easily create adaptive cards from the response.

dotnet/src/Microsoft.Agents.AI.Anthropic/AnthropicBetaServiceExtensions.cs

@@ -45,14 +45,20 @@ public static ChatClientAgent CreateAIAgent(
     {
         var options = new ChatClientAgentOptions
         {
-            Instructions = instructions,
             Name = name,
             Description = description,
         };
 
+        if (!string.IsNullOrWhiteSpace(instructions))
+        {
+            options.ChatOptions ??= new();
+            options.ChatOptions.Instructions = instructions;
+        }
+
         if (tools is { Count: > 0 })
         {
-            options.ChatOptions = new ChatOptions { Tools = tools };
+            options.ChatOptions ??= new();
+            options.ChatOptions.Tools = tools;
         }
 
         var chatClient = betaService.AsIChatClient(model, defaultMaxTokens ?? DefaultMaxTokens);

dotnet/src/Microsoft.Agents.AI.Anthropic/AnthropicClientExtensions.cs

@@ -45,14 +45,20 @@ public static ChatClientAgent CreateAIAgent(
     {
         var options = new ChatClientAgentOptions
         {
-            Instructions = instructions,
             Name = name,
             Description = description,
         };
 
+        if (!string.IsNullOrWhiteSpace(instructions))
+        {
+            options.ChatOptions ??= new();
+            options.ChatOptions.Instructions = instructions;
+        }
+
         if (tools is { Count: > 0 })
         {
-            options.ChatOptions = new ChatOptions { Tools = tools };
+            options.ChatOptions ??= new();
+            options.ChatOptions.Tools = tools;
         }
 
         var chatClient = client.AsIChatClient(model, defaultMaxTokens ?? DefaultMaxTokens);