Skip to content

Commit bdf15a8

Browse files
authored
.Net Agents - ChatCompletionAgent Pre-Graduation (#7900)
### Motivation and Context <!-- Thank you for your contribution to the semantic-kernel repo! Please help reviewers and future users, providing the following information: 1. Why is this change required? 2. What problem does it solve? 3. What scenario does it contribute to? 4. If it fixes an open issue, please link to the issue here. --> Update public signatures / interface of `ChatCompletionAgent` in preparation for removing experimental tag. Fixes: #6037 Fixes: #6523 ### Description <!-- Describe your changes, the overall approach, the underlying design. These notes will help understanding how your code works. Thanks! --> - Include `Kernel` and `KernelArguments` in agent invocation signatures for `ChatCompletionAgent` - Change `ChatCompletionAgent.ExeuctionSettings` to `ChatCompletionAgent.KernelArguments` - Mirror pattern for `OpenAIAssistantAgent` - Integrate `Kernel` and `KernelArguments.ExecutionSettings` as overrides for agent invocation - Added new sample that explores the entire selection matrix: `ChatCompletion_ServiceSelection` ### Contribution Checklist <!-- Before submitting this PR, please make sure: --> - [X] The code builds clean without any errors or warnings - [X] The PR follows the [SK Contribution Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md) and the [pre-submission formatting script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts) raises no violations - [X] All unit tests pass, and I have added new tests where possible - [X] I didn't break anyone 😄
1 parent f71d326 commit bdf15a8

15 files changed

Lines changed: 218 additions & 27 deletions

‎dotnet/samples/Concepts/Agents/ChatCompletion_FunctionTermination.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ public async Task UseAutoFunctionInvocationFilterWithAgentInvocationAsync()
2323
{
2424
Instructions = "Answer questions about the menu.",
2525
Kernel = CreateKernelWithFilter(),
26-
ExecutionSettings = new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions },
26+
Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions }),
2727
};
2828

2929
KernelPlugin plugin = KernelPluginFactory.CreateFromType<MenuPlugin>();
@@ -76,7 +76,7 @@ public async Task UseAutoFunctionInvocationFilterWithAgentChatAsync()
7676
{
7777
Instructions = "Answer questions about the menu.",
7878
Kernel = CreateKernelWithFilter(),
79-
ExecutionSettings = new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions },
79+
Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions }),
8080
};
8181

8282
KernelPlugin plugin = KernelPluginFactory.CreateFromType<MenuPlugin>();
Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
using Microsoft.SemanticKernel;
3+
using Microsoft.SemanticKernel.Agents;
4+
using Microsoft.SemanticKernel.ChatCompletion;
5+
using Microsoft.SemanticKernel.Connectors.OpenAI;
6+
7+
namespace Agents;
8+
9+
/// <summary>
10+
/// Demonstrate service selection for <see cref="ChatCompletionAgent"/> through setting service-id
11+
/// on <see cref="ChatCompletionAgent.Arguments"/> and also providing override <see cref="KernelArguments"/>
12+
/// when calling <see cref="ChatCompletionAgent.InvokeAsync"/>
13+
/// </summary>
14+
public class ChatCompletion_ServiceSelection(ITestOutputHelper output) : BaseTest(output)
15+
{
16+
private const string ServiceKeyGood = "chat-good";
17+
private const string ServiceKeyBad = "chat-bad";
18+
19+
[Fact]
20+
public async Task UseServiceSelectionWithChatCompletionAgentAsync()
21+
{
22+
// Create kernel with two instances of IChatCompletionService
23+
// One service is configured with a valid API key and the other with an
24+
// invalid key that will result in a 401 Unauthorized error.
25+
Kernel kernel = CreateKernelWithTwoServices();
26+
27+
// Define the agent targeting ServiceId = ServiceKeyGood
28+
ChatCompletionAgent agentGood =
29+
new()
30+
{
31+
Kernel = kernel,
32+
Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ServiceId = ServiceKeyGood }),
33+
};
34+
35+
// Define the agent targeting ServiceId = ServiceKeyBad
36+
ChatCompletionAgent agentBad =
37+
new()
38+
{
39+
Kernel = kernel,
40+
Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ServiceId = ServiceKeyBad }),
41+
};
42+
43+
// Define the agent with no explicit ServiceId defined
44+
ChatCompletionAgent agentDefault = new() { Kernel = kernel };
45+
46+
// Invoke agent as initialized with ServiceId = ServiceKeyGood: Expect agent response
47+
Console.WriteLine("\n[Agent With Good ServiceId]");
48+
await InvokeAgentAsync(agentGood);
49+
50+
// Invoke agent as initialized with ServiceId = ServiceKeyBad: Expect failure due to invalid service key
51+
Console.WriteLine("\n[Agent With Bad ServiceId]");
52+
await InvokeAgentAsync(agentBad);
53+
54+
// Invoke agent as initialized with no explicit ServiceId: Expect agent response
55+
Console.WriteLine("\n[Agent With No ServiceId]");
56+
await InvokeAgentAsync(agentDefault);
57+
58+
// Invoke agent with override arguments where ServiceId = ServiceKeyGood: Expect agent response
59+
Console.WriteLine("\n[Bad Agent: Good ServiceId Override]");
60+
await InvokeAgentAsync(agentBad, new(new OpenAIPromptExecutionSettings() { ServiceId = ServiceKeyGood }));
61+
62+
// Invoke agent with override arguments where ServiceId = ServiceKeyBad: Expect failure due to invalid service key
63+
Console.WriteLine("\n[Good Agent: Bad ServiceId Override]");
64+
await InvokeAgentAsync(agentGood, new(new OpenAIPromptExecutionSettings() { ServiceId = ServiceKeyBad }));
65+
Console.WriteLine("\n[Default Agent: Bad ServiceId Override]");
66+
await InvokeAgentAsync(agentDefault, new(new OpenAIPromptExecutionSettings() { ServiceId = ServiceKeyBad }));
67+
68+
// Invoke agent with override arguments with no explicit ServiceId: Expect agent response
69+
Console.WriteLine("\n[Good Agent: No ServiceId Override]");
70+
await InvokeAgentAsync(agentGood, new(new OpenAIPromptExecutionSettings()));
71+
Console.WriteLine("\n[Bad Agent: No ServiceId Override]");
72+
await InvokeAgentAsync(agentBad, new(new OpenAIPromptExecutionSettings()));
73+
Console.WriteLine("\n[Default Agent: No ServiceId Override]");
74+
await InvokeAgentAsync(agentDefault, new(new OpenAIPromptExecutionSettings()));
75+
76+
// Local function to invoke agent and display the conversation messages.
77+
async Task InvokeAgentAsync(ChatCompletionAgent agent, KernelArguments? arguments = null)
78+
{
79+
ChatHistory chat = [new(AuthorRole.User, "Hello")];
80+
81+
try
82+
{
83+
await foreach (ChatMessageContent response in agent.InvokeAsync(chat, arguments))
84+
{
85+
Console.WriteLine(response.Content);
86+
}
87+
}
88+
catch (HttpOperationException exception)
89+
{
90+
Console.WriteLine($"Status: {exception.StatusCode}");
91+
}
92+
}
93+
}
94+
95+
private Kernel CreateKernelWithTwoServices()
96+
{
97+
IKernelBuilder builder = Kernel.CreateBuilder();
98+
99+
if (this.UseOpenAIConfig)
100+
{
101+
builder.AddOpenAIChatCompletion(
102+
TestConfiguration.OpenAI.ChatModelId,
103+
"bad-key",
104+
serviceId: ServiceKeyBad);
105+
106+
builder.AddOpenAIChatCompletion(
107+
TestConfiguration.OpenAI.ChatModelId,
108+
TestConfiguration.OpenAI.ApiKey,
109+
serviceId: ServiceKeyGood);
110+
}
111+
else
112+
{
113+
builder.AddAzureOpenAIChatCompletion(
114+
TestConfiguration.AzureOpenAI.ChatDeploymentName,
115+
TestConfiguration.AzureOpenAI.Endpoint,
116+
"bad-key",
117+
serviceId: ServiceKeyBad);
118+
119+
builder.AddAzureOpenAIChatCompletion(
120+
TestConfiguration.AzureOpenAI.ChatDeploymentName,
121+
TestConfiguration.AzureOpenAI.Endpoint,
122+
TestConfiguration.AzureOpenAI.ApiKey,
123+
serviceId: ServiceKeyGood);
124+
}
125+
126+
return builder.Build();
127+
}
128+
}

‎dotnet/samples/Concepts/Agents/ChatCompletion_Streaming.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ public async Task UseStreamingChatCompletionAgentWithPluginAsync()
4949
Name = "Host",
5050
Instructions = MenuInstructions,
5151
Kernel = this.CreateKernelWithChatCompletion(),
52-
ExecutionSettings = new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions },
52+
Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions }),
5353
};
5454

5555
// Initialize plugin and add to the agent's Kernel (same as direct Kernel usage).

‎dotnet/samples/GettingStartedWithAgents/Step2_Plugins.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ public async Task UseChatCompletionWithPluginAgentAsync()
2626
Instructions = HostInstructions,
2727
Name = HostName,
2828
Kernel = this.CreateKernelWithChatCompletion(),
29-
ExecutionSettings = new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions },
29+
Arguments = new KernelArguments(new OpenAIPromptExecutionSettings() { ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions }),
3030
};
3131

3232
// Initialize plugin and add to the agent's Kernel (same as direct Kernel usage).

‎dotnet/src/Agents/Abstractions/KernelAgent.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,5 +17,5 @@ public abstract class KernelAgent : Agent
1717
/// <remarks>
1818
/// Defaults to empty Kernel, but may be overridden.
1919
/// </remarks>
20-
public Kernel Kernel { get; init; } = new Kernel();
20+
public Kernel Kernel { get; init; } = new();
2121
}

‎dotnet/src/Agents/Core/ChatCompletionAgent.cs‎

Lines changed: 33 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
using Microsoft.Extensions.Logging;
88
using Microsoft.SemanticKernel.Agents.History;
99
using Microsoft.SemanticKernel.ChatCompletion;
10+
using Microsoft.SemanticKernel.Services;
1011

1112
namespace Microsoft.SemanticKernel.Agents;
1213

@@ -15,24 +16,29 @@ namespace Microsoft.SemanticKernel.Agents;
1516
/// </summary>
1617
/// <remarks>
1718
/// NOTE: Enable OpenAIPromptExecutionSettings.ToolCallBehavior for agent plugins.
18-
/// (<see cref="ChatCompletionAgent.ExecutionSettings"/>)
19+
/// (<see cref="ChatCompletionAgent.Arguments"/>)
1920
/// </remarks>
2021
public sealed class ChatCompletionAgent : KernelAgent, IChatHistoryHandler
2122
{
2223
/// <summary>
23-
/// Optional execution settings for the agent.
24+
/// Optional arguments for the agent.
2425
/// </summary>
25-
public PromptExecutionSettings? ExecutionSettings { get; set; }
26+
public KernelArguments? Arguments { get; init; }
2627

2728
/// <inheritdoc/>
2829
public IChatHistoryReducer? HistoryReducer { get; init; }
2930

3031
/// <inheritdoc/>
3132
public async IAsyncEnumerable<ChatMessageContent> InvokeAsync(
3233
ChatHistory history,
34+
KernelArguments? arguments = null,
35+
Kernel? kernel = null,
3336
[EnumeratorCancellation] CancellationToken cancellationToken = default)
3437
{
35-
IChatCompletionService chatCompletionService = this.Kernel.GetRequiredService<IChatCompletionService>();
38+
kernel ??= this.Kernel;
39+
arguments ??= this.Arguments;
40+
41+
(IChatCompletionService chatCompletionService, PromptExecutionSettings? executionSettings) = this.GetChatCompletionService(kernel, arguments);
3642

3743
ChatHistory chat = this.SetupAgentChatHistory(history);
3844

@@ -43,8 +49,8 @@ public async IAsyncEnumerable<ChatMessageContent> InvokeAsync(
4349
IReadOnlyList<ChatMessageContent> messages =
4450
await chatCompletionService.GetChatMessageContentsAsync(
4551
chat,
46-
this.ExecutionSettings,
47-
this.Kernel,
52+
executionSettings,
53+
kernel,
4854
cancellationToken).ConfigureAwait(false);
4955

5056
this.Logger.LogAgentChatServiceInvokedAgent(nameof(InvokeAsync), this.Id, chatCompletionService.GetType(), messages.Count);
@@ -61,7 +67,6 @@ await chatCompletionService.GetChatMessageContentsAsync(
6167

6268
foreach (ChatMessageContent message in messages ?? [])
6369
{
64-
// TODO: MESSAGE SOURCE - ISSUE #5731
6570
message.AuthorName = this.Name;
6671

6772
yield return message;
@@ -71,9 +76,14 @@ await chatCompletionService.GetChatMessageContentsAsync(
7176
/// <inheritdoc/>
7277
public async IAsyncEnumerable<StreamingChatMessageContent> InvokeStreamingAsync(
7378
ChatHistory history,
79+
KernelArguments? arguments = null,
80+
Kernel? kernel = null,
7481
[EnumeratorCancellation] CancellationToken cancellationToken = default)
7582
{
76-
IChatCompletionService chatCompletionService = this.Kernel.GetRequiredService<IChatCompletionService>();
83+
kernel ??= this.Kernel;
84+
arguments ??= this.Arguments;
85+
86+
(IChatCompletionService chatCompletionService, PromptExecutionSettings? executionSettings) = this.GetChatCompletionService(kernel, arguments);
7787

7888
ChatHistory chat = this.SetupAgentChatHistory(history);
7989

@@ -84,15 +94,14 @@ public async IAsyncEnumerable<StreamingChatMessageContent> InvokeStreamingAsync(
8494
IAsyncEnumerable<StreamingChatMessageContent> messages =
8595
chatCompletionService.GetStreamingChatMessageContentsAsync(
8696
chat,
87-
this.ExecutionSettings,
88-
this.Kernel,
97+
executionSettings,
98+
kernel,
8999
cancellationToken);
90100

91101
this.Logger.LogAgentChatServiceInvokedStreamingAgent(nameof(InvokeAsync), this.Id, chatCompletionService.GetType());
92102

93103
await foreach (StreamingChatMessageContent message in messages.ConfigureAwait(false))
94104
{
95-
// TODO: MESSAGE SOURCE - ISSUE #5731
96105
message.AuthorName = this.Name;
97106

98107
yield return message;
@@ -136,6 +145,19 @@ protected override Task<AgentChannel> CreateChannelAsync(CancellationToken cance
136145
return Task.FromResult<AgentChannel>(channel);
137146
}
138147

148+
private (IChatCompletionService service, PromptExecutionSettings? executionSettings) GetChatCompletionService(Kernel kernel, KernelArguments? arguments)
149+
{
150+
// Need to provide a KernelFunction to the service selector as a container for the execution-settings.
151+
KernelFunction nullPrompt = KernelFunctionFactory.CreateFromPrompt("placeholder", arguments?.ExecutionSettings?.Values);
152+
(IChatCompletionService chatCompletionService, PromptExecutionSettings? executionSettings) =
153+
kernel.ServiceSelector.SelectAIService<IChatCompletionService>(
154+
kernel,
155+
nullPrompt,
156+
arguments ?? []);
157+
158+
return (chatCompletionService, executionSettings);
159+
}
160+
139161
private ChatHistory SetupAgentChatHistory(IReadOnlyList<ChatMessageContent> history)
140162
{
141163
ChatHistory chat = [];

‎dotnet/src/Agents/Core/ChatHistoryChannel.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ public sealed class ChatHistoryChannel : AgentChannel
3838
Queue<ChatMessageContent> messageQueue = [];
3939

4040
ChatMessageContent? yieldMessage = null;
41-
await foreach (ChatMessageContent responseMessage in historyHandler.InvokeAsync(this._history, cancellationToken).ConfigureAwait(false))
41+
await foreach (ChatMessageContent responseMessage in historyHandler.InvokeAsync(this._history, null, null, cancellationToken).ConfigureAwait(false))
4242
{
4343
// Capture all messages that have been included in the mutated the history.
4444
for (int messageIndex = messageCount; messageIndex < this._history.Count; messageIndex++)

‎dotnet/src/Agents/Core/IChatHistoryHandler.cs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,19 +20,27 @@ public interface IChatHistoryHandler
2020
/// Entry point for calling into an agent from a <see cref="ChatHistoryChannel"/>.
2121
/// </summary>
2222
/// <param name="history">The chat history at the point the channel is created.</param>
23+
/// <param name="arguments">Optional arguments to pass to the agents's invocation, including any <see cref="PromptExecutionSettings"/>.</param>
24+
/// <param name="kernel">The <see cref="Kernel"/> containing services, plugins, and other state for use by the agent.</param>
2325
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
2426
/// <returns>Asynchronous enumeration of messages.</returns>
2527
IAsyncEnumerable<ChatMessageContent> InvokeAsync(
2628
ChatHistory history,
29+
KernelArguments? arguments = null,
30+
Kernel? kernel = null,
2731
CancellationToken cancellationToken = default);
2832

2933
/// <summary>
3034
/// Entry point for calling into an agent from a <see cref="ChatHistoryChannel"/> for streaming content.
3135
/// </summary>
3236
/// <param name="history">The chat history at the point the channel is created.</param>
37+
/// <param name="arguments">Optional arguments to pass to the agents's invocation, including any <see cref="PromptExecutionSettings"/>.</param>
38+
/// <param name="kernel">Optional <see cref="Kernel"/> override containing services, plugins, and other state for use by the agent.</param>
3339
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
3440
/// <returns>Asynchronous enumeration of streaming content.</returns>
3541
IAsyncEnumerable<StreamingChatMessageContent> InvokeStreamingAsync(
3642
ChatHistory history,
43+
KernelArguments? arguments = null,
44+
Kernel? kernel = null,
3745
CancellationToken cancellationToken = default);
3846
}

‎dotnet/src/Agents/OpenAI/AssistantThreadActions.cs‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -109,22 +109,29 @@ public static async IAsyncEnumerable<ChatMessageContent> GetMessagesAsync(Assist
109109
/// <param name="threadId">The thread identifier</param>
110110
/// <param name="pollingConfiguration">Config to utilize when polling for run state.</param>
111111
/// <param name="logger">The logger to utilize (might be agent or channel scoped)</param>
112+
/// <param name="kernel">The <see cref="Kernel"/> plugins and other state.</param>
113+
/// <param name="arguments">Optional arguments to pass to the agents's invocation, including any <see cref="PromptExecutionSettings"/>.</param>
112114
/// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
113115
/// <returns>Asynchronous enumeration of messages.</returns>
116+
/// <remarks>
117+
/// The `arguments` parameter is not currently used by the agent, but is provided for future extensibility.
118+
/// </remarks>
114119
public static async IAsyncEnumerable<(bool IsVisible, ChatMessageContent Message)> InvokeAsync(
115120
OpenAIAssistantAgent agent,
116121
AssistantsClient client,
117122
string threadId,
118123
OpenAIAssistantConfiguration.PollingConfiguration pollingConfiguration,
119124
ILogger logger,
125+
Kernel kernel,
126+
KernelArguments? arguments,
120127
[EnumeratorCancellation] CancellationToken cancellationToken)
121128
{
122129
if (agent.IsDeleted)
123130
{
124131
throw new KernelException($"Agent Failure - {nameof(OpenAIAssistantAgent)} agent is deleted: {agent.Id}.");
125132
}
126133

127-
ToolDefinition[]? tools = [.. agent.Tools, .. agent.Kernel.Plugins.SelectMany(p => p.Select(f => f.ToToolDefinition(p.Name, FunctionDelimiter)))];
134+
ToolDefinition[]? tools = [.. agent.Tools, .. kernel.Plugins.SelectMany(p => p.Select(f => f.ToToolDefinition(p.Name, FunctionDelimiter)))];
128135

129136
logger.LogOpenAIAssistantCreatingRun(nameof(InvokeAsync), threadId);
130137

0 commit comments

Comments
 (0)