agent/agent-framework
2
0
Fork 0
mirror of https://github.com/microsoft/agent-framework.git synced 2026-06-16 21:04:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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>
This commit is contained in:
Roger Barreto
2025-12-03 13:39:47 +00:00
committed by GitHub
Unverified
parent e9ab514696
commit 6232dd8305
53 changed files with 393 additions and 365 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dotnet/src/Microsoft.Agents.AI.Anthropic/AnthropicBetaServiceExtensions.cs
+8 -2
View File
@@ -45,14 +45,20 @@ public static class AnthropicBetaServiceExtensions
{
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
+8 -2
View File
@@ -45,14 +45,20 @@ public static class AnthropicClientExtensions
{
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);
dotnet/src/Microsoft.Agents.AI.AzureAI.Persistent/PersistentAgentsClientExtensions.cs
+14 -4
View File
@@ -67,12 +67,17 @@ public static class PersistentAgentsClientExtensions
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
}, services: services);
}
@@ -207,12 +212,17 @@ public static class PersistentAgentsClientExtensions
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,
@@ -453,7 +463,7 @@ public static class PersistentAgentsClientExtensions
model: model,
name: options.Name,
description: options.Description,
instructions: options.Instructions,
instructions: options.ChatOptions?.Instructions,
tools: toolDefinitionsAndResources.ToolDefinitions,
toolResources: toolDefinitionsAndResources.ToolResources,
temperature: null,
@@ -513,7 +523,7 @@ public static class PersistentAgentsClientExtensions
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.AzureAI/AzureAIProjectChatClientExtensions.cs
+3 -4
View File
@@ -393,7 +393,7 @@ public static partial class AzureAIProjectChatClientExtensions
PromptAgentDefinition agentDefinition = new(model)
{
Instructions = options.Instructions,
Instructions = options.ChatOptions?.Instructions,
Temperature = options.ChatOptions?.Temperature,
TopP = options.ChatOptions?.TopP,
TextOptions = new() { TextFormat = ToOpenAIResponseTextFormat(options.ChatOptions?.ResponseFormat, options.ChatOptions) }
@@ -459,7 +459,7 @@ public static partial class AzureAIProjectChatClientExtensions
PromptAgentDefinition agentDefinition = new(model)
{
Instructions = options.Instructions,
Instructions = options.ChatOptions?.Instructions,
Temperature = options.ChatOptions?.Temperature,
TopP = options.ChatOptions?.TopP,
TextOptions = new() { TextFormat = ToOpenAIResponseTextFormat(options.ChatOptions?.ResponseFormat, options.ChatOptions) }
@@ -822,10 +822,9 @@ public static partial class AzureAIProjectChatClientExtensions
if (agentDefinition is PromptAgentDefinition promptAgentDefinition)
{
agentOptions.ChatOptions ??= chatOptions?.Clone() ?? new();
agentOptions.Instructions = promptAgentDefinition.Instructions;
agentOptions.ChatOptions.Instructions = promptAgentDefinition.Instructions;
agentOptions.ChatOptions.Temperature = promptAgentDefinition.Temperature;
agentOptions.ChatOptions.TopP = promptAgentDefinition.TopP;
agentOptions.ChatOptions.Instructions = promptAgentDefinition.Instructions;
}
if (agentTools is { Count: > 0 })
dotnet/src/Microsoft.Agents.AI.Declarative/ChatClient/ChatClientPromptAgentFactory.cs
-1
View File
@@ -38,7 +38,6 @@ public sealed class ChatClientPromptAgentFactory : PromptAgentFactory
{
Name = promptAgent.Name,
Description = promptAgent.Description,
Instructions = promptAgent.Instructions?.ToTemplateString(),
ChatOptions = promptAgent.GetChatOptions(this.Engine, this._functions),
};
dotnet/src/Microsoft.Agents.AI.Declarative/Extensions/PromptAgentExtensions.cs
+1 -1
View File
@@ -35,7 +35,7 @@ public static class PromptAgentExtensions
return new ChatOptions()
{
Instructions = promptAgent.ResponseInstructions?.ToTemplateString(),
Instructions = promptAgent.Instructions?.ToTemplateString(),
Temperature = (float?)modelOptions?.Temperature?.Eval(engine),
MaxOutputTokens = (int?)modelOptions?.MaxOutputTokens?.Eval(engine),
TopP = (float?)modelOptions?.TopP?.Eval(engine),
dotnet/src/Microsoft.Agents.AI.OpenAI/Extensions/OpenAIAssistantClientExtensions.cs
+18 -8
View File
@@ -77,12 +77,17 @@ public static class OpenAIAssistantClientExtensions
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
}, services: services);
}
@@ -215,12 +220,17 @@ public static class OpenAIAssistantClientExtensions
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,
@@ -339,10 +349,10 @@ public static class OpenAIAssistantClientExtensions
{
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,
@@ -377,7 +387,7 @@ public static class OpenAIAssistantClientExtensions
{
Name = options.Name,
Description = options.Description,
Instructions = options.Instructions,
Instructions = options.ChatOptions?.Instructions,
};
// Convert AITools to ToolDefinitions and ToolResources
@@ -443,10 +453,10 @@ public static class OpenAIAssistantClientExtensions
{
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,
@@ -484,7 +494,7 @@ public static class OpenAIAssistantClientExtensions
{
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
+2 -2
View File
@@ -47,9 +47,9 @@ public static class OpenAIChatClientExtensions
{
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
+2 -2
View File
@@ -50,9 +50,9 @@ public static class OpenAIResponseClientExtensions
{
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
+1 -1
View File
@@ -32,7 +32,7 @@ public class OpenAIChatClientAgent : DelegatingAIAgent
{
Name = name,
Description = description,
Instructions = instructions,
ChatOptions = new ChatOptions() { Instructions = instructions },
}, loggerFactory)
{
}
dotnet/src/Microsoft.Agents.AI.OpenAI/OpenAIResponseClientAgent.cs
+1 -1
View File
@@ -32,7 +32,7 @@ public class OpenAIResponseClientAgent : DelegatingAIAgent
{
Name = name,
Description = description,
Instructions = instructions,
ChatOptions = new ChatOptions() { Instructions = instructions },
}, loggerFactory)
{
}
dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs
+13 -13
View File
@@ -59,13 +59,13 @@ public sealed partial class ChatClientAgent : AIAgent
chatClient,
new ChatClientAgentOptions
{
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
},
Name = name,
Description = description
},
loggerFactory,
services)
@@ -141,7 +141,7 @@ public sealed partial class ChatClientAgent : AIAgent
/// These instructions are typically provided to the AI model as system messages to establish
/// the context and expected behavior for the agent's responses.
/// </remarks>
public string? Instructions => this._agentOptions?.Instructions;
public string? Instructions => this._agentOptions?.ChatOptions?.Instructions;
/// <summary>
/// Gets of the default <see cref="ChatOptions"/> used by the agent.
@@ -492,7 +492,6 @@ public sealed partial class ChatClientAgent : AIAgent
requestChatOptions.AllowMultipleToolCalls ??= this._agentOptions.ChatOptions.AllowMultipleToolCalls;
requestChatOptions.ConversationId ??= this._agentOptions.ChatOptions.ConversationId;
requestChatOptions.FrequencyPenalty ??= this._agentOptions.ChatOptions.FrequencyPenalty;
requestChatOptions.Instructions ??= this._agentOptions.ChatOptions.Instructions;
requestChatOptions.MaxOutputTokens ??= this._agentOptions.ChatOptions.MaxOutputTokens;
requestChatOptions.ModelId ??= this._agentOptions.ChatOptions.ModelId;
requestChatOptions.PresencePenalty ??= this._agentOptions.ChatOptions.PresencePenalty;
@@ -503,6 +502,13 @@ public sealed partial class ChatClientAgent : AIAgent
requestChatOptions.TopK ??= this._agentOptions.ChatOptions.TopK;
requestChatOptions.ToolMode ??= this._agentOptions.ChatOptions.ToolMode;
// Merge instructions by concatenating them if both are present.
requestChatOptions.Instructions = !string.IsNullOrWhiteSpace(requestChatOptions.Instructions) && !string.IsNullOrWhiteSpace(this.Instructions)
? $"{this.Instructions}\n{requestChatOptions.Instructions}"
: (!string.IsNullOrWhiteSpace(requestChatOptions.Instructions)
? requestChatOptions.Instructions
: this.Instructions);
// Merge only the additional properties from the agent if they are not already set in the request options.
if (requestChatOptions.AdditionalProperties is not null && this._agentOptions.ChatOptions.AdditionalProperties is not null)
{
@@ -685,12 +691,6 @@ public sealed partial class ChatClientAgent : AIAgent
""");
}
if (!string.IsNullOrWhiteSpace(this.Instructions))
{
chatOptions ??= new();
chatOptions.Instructions = string.IsNullOrWhiteSpace(chatOptions.Instructions) ? this.Instructions : $"{this.Instructions}\n{chatOptions.Instructions}";
}
// Only create or update ChatOptions if we have an id on the thread and we don't have the same one already in ChatOptions.
if (!string.IsNullOrWhiteSpace(typedThread.ConversationId) && typedThread.ConversationId != chatOptions?.ConversationId)
{
dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs
-36
View File
@@ -1,7 +1,6 @@
// Copyright (c) Microsoft. All rights reserved.
using System;
using System.Collections.Generic;
using System.Text.Json;
using Microsoft.Extensions.AI;
@@ -17,35 +16,6 @@ namespace Microsoft.Agents.AI;
/// </remarks>
public class ChatClientAgentOptions
{
/// <summary>
/// Initializes a new instance of the <see cref="ChatClientAgentOptions"/> class.
/// </summary>
public ChatClientAgentOptions()
{
}
/// <summary>
/// Initializes a new instance of the <see cref="ChatClientAgentOptions"/> class with the specified parameters.
/// </summary>
/// <remarks>If <paramref name="tools"/> is provided, a new <see cref="ChatOptions"/> instance is created
/// with the specified instructions and tools.</remarks>
/// <param name="instructions">The instructions or guidelines for the chat client agent. Can be <see langword="null"/> if not specified.</param>
/// <param name="name">The name of the chat client agent. Can be <see langword="null"/> if not specified.</param>
/// <param name="description">The description of the chat client agent. Can be <see langword="null"/> if not specified.</param>
/// <param name="tools">A list of <see cref="AITool"/> instances available to the chat client agent. Can be <see langword="null"/> if no
/// tools are specified.</param>
public ChatClientAgentOptions(string? instructions, string? name = null, string? description = null, IList<AITool>? tools = null)
{
this.Name = name;
this.Instructions = instructions;
this.Description = description;
if (tools is not null)
{
(this.ChatOptions ??= new()).Tools = tools;
}
}
/// <summary>
/// Gets or sets the agent id.
/// </summary>
@@ -56,11 +26,6 @@ public class ChatClientAgentOptions
/// </summary>
public string? Name { get; set; }
/// <summary>
/// Gets or sets the agent instructions.
/// </summary>
public string? Instructions { get; set; }
/// <summary>
/// Gets or sets the agent description.
/// </summary>
@@ -106,7 +71,6 @@ public class ChatClientAgentOptions
{
Id = this.Id,
Name = this.Name,
Instructions = this.Instructions,
Description = this.Description,
ChatOptions = this.ChatOptions?.Clone(),
ChatMessageStoreFactory = this.ChatMessageStoreFactory,