Skip to content

Commit 1370903

Browse files
authored
.NET: [BREAKING] Better support tool changes between runs (#8754)
* Better support tool changes between runs * Address PR comments
1 parent 3efb73a commit 1370903

10 files changed

Lines changed: 1256 additions & 46 deletions

‎dotnet/src/Microsoft.Agents.AI/ChatClient/ApprovalNotRequiredFunctionBypassingChatClient.cs‎

Lines changed: 50 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,14 @@ namespace Microsoft.Agents.AI;
3333
/// <see cref="FunctionInvokingChatClient"/> can process them alongside the caller's human-approved responses.
3434
/// </para>
3535
/// <para>
36+
/// A stored decision is only reused while the tool it refers to still does not require approval. Before
37+
/// re-injecting, each stored item is re-checked against the tools available to the current turn. If the name
38+
/// has since become approval-required, or has left the tool set, the stored decision is discarded and the call
39+
/// is injected as rejected rather than approved, so that it is not executed. The decision recorded here was the
40+
/// framework's to make only while no approval was needed; once the application asks for a human, a decision
41+
/// taken before that cannot stand in for one.
42+
/// </para>
43+
/// <para>
3644
/// This decorator operates within the context of a running <see cref="AIAgent"/> with an active
3745
/// <see cref="AgentRunContext.Session"/>. When invoked without an ambient run context or session
3846
/// (for example when the chat client is used directly outside of an agent run), the decorator becomes
@@ -76,12 +84,12 @@ public override async Task<ChatResponse> GetResponseAsync(
7684

7785
var autoApprovableNames = ApprovalRequirement.GetApprovalNotRequiredToolNames(this, options);
7886

79-
var (messagesToSend, injectedAutoApprovals) = InjectPendingAutoApprovals(messages, session);
87+
var (messagesToSend, injectedAutoApprovals) = this.PrepareStoredAutoApprovals(messages, session, autoApprovableNames);
8088

8189
var response = await base.GetResponseAsync(messagesToSend, options, cancellationToken).ConfigureAwait(false);
8290

83-
// The injected auto-approvals are cleared only now that the run has succeeded, so a failed run leaves them
84-
// in the session and the next run injects them again instead of leaving the tool calls unanswered.
91+
// The injected responses are cleared only now that the run has succeeded, so a failed run leaves them in
92+
// the session and the next run injects them again instead of leaving the tool calls unanswered.
8593
if (injectedAutoApprovals)
8694
{
8795
session.StateBag.TryRemoveValue(StateBagKey);
@@ -110,7 +118,8 @@ public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseA
110118

111119
var autoApprovableNames = ApprovalRequirement.GetApprovalNotRequiredToolNames(this, options);
112120

113-
var (messagesToSend, injectedAutoApprovals) = InjectPendingAutoApprovals(messages, session);
121+
var (messagesToSend, injectedAutoApprovals) = this.PrepareStoredAutoApprovals(messages, session, autoApprovableNames);
122+
114123
List<ToolApprovalRequestContent>? autoApproved = null;
115124

116125
// Set only once the stream has run to completion, so that any abnormal end - an exception from the inner
@@ -177,41 +186,63 @@ private bool TryGetSession([NotNullWhen(true)] out AgentSession? session)
177186
[LoggerMessage(LogLevel.Warning, "ApprovalNotRequiredFunctionBypassingChatClient was invoked without an active agent run context or session. Approval-not-required function bypassing is skipped and all approval requests are surfaced to the caller. Invoke the chat client through AIAgent.RunAsync or AIAgent.RunStreamingAsync to enable bypassing.")]
178187
private static partial void LogBypassingSkipped(ILogger logger);
179188

189+
[LoggerMessage(LogLevel.Warning, "A tool call to '{ToolName}' was stored for automatic approval on a previous turn, but the tool available under that name now requires approval or is no longer available. The stored approval is discarded and the call is rejected rather than executed.")]
190+
private static partial void LogStaleAutoApprovalRejected(ILogger logger, string toolName);
191+
180192
/// <summary>
181-
/// Checks the session for stored auto-approvals from a previous turn and injects them as
182-
/// a user message containing <see cref="ToolApprovalResponseContent"/> items appended to the input messages.
193+
/// Checks the session for stored auto-approvals from a previous turn and decides, per stored request and
194+
/// against the tools available to the current turn, whether it can still be injected as approved.
183195
/// </summary>
184196
/// <remarks>
185-
/// All stored requests are unconditionally injected as approved responses regardless of whether the
186-
/// tool set has changed, because the LLM requires a complete set of tool call responses for a prior turn.
197+
/// <para>
198+
/// A stored request records that a tool did not require approval at the time the decision was made, which
199+
/// made the decision the framework's to take on the caller's behalf. Approval requirements can change
200+
/// between turns, so each stored request is re-checked before it is used. If the tool that would now run
201+
/// requires approval, or is no longer available at all, the stored decision no longer stands and the call is
202+
/// injected as rejected instead of approved, so that it is not executed.
203+
/// </para>
204+
/// <para>
205+
/// A tool being replaced between turns is not in itself a reason to reject anything, and routinely happens as
206+
/// an agent is developed. Only a change in whether approval is required matters here.
207+
/// </para>
187208
/// </remarks>
188209
/// <returns>
189-
/// The messages to send to the inner client, and whether any auto-approvals were injected into them. The
190-
/// stored auto-approvals are cleared by the caller only once the run has completed successfully, so that a
191-
/// failed run leaves them in the session and the next run injects them again rather than leaving the
192-
/// auto-approved calls unanswered.
210+
/// The messages to send to the inner client, and whether any responses were injected into them. The stored
211+
/// auto-approvals are cleared by the caller only once the run has completed successfully, so that a failed
212+
/// run leaves them in the session and the next run injects them again rather than leaving the calls
213+
/// unanswered.
193214
/// </returns>
194-
private static (IEnumerable<ChatMessage> Messages, bool Injected) InjectPendingAutoApprovals(
215+
private (IEnumerable<ChatMessage> Messages, bool Injected) PrepareStoredAutoApprovals(
195216
IEnumerable<ChatMessage> messages,
196-
AgentSession session)
217+
AgentSession session,
218+
HashSet<string> autoApprovableNames)
197219
{
198-
if (!session.StateBag.TryGetValue<List<ToolApprovalRequestContent>>(
220+
if (!session.StateBag.TryGetValue(
199221
StateBagKey,
200-
out var pendingRequests,
222+
out List<ToolApprovalRequestContent>? pendingRequests,
201223
AgentJsonUtilities.DefaultOptions)
202224
|| pendingRequests is not { Count: > 0 })
203225
{
204226
return (messages, false);
205227
}
206228

229+
// We have some requests that didn't require approval on the last run.
230+
// Let's check each one to make sure they didn't become approval required in the meantime.
207231
List<AIContent> approvalResponses = [];
232+
208233
foreach (var request in pendingRequests)
209234
{
210-
approvalResponses.Add(request.CreateResponse(approved: true));
235+
bool stillApprovalNotRequired = ApprovalRequirement.IsApprovalNotRequired(request.ToolCall, autoApprovableNames);
236+
237+
if (!stillApprovalNotRequired)
238+
{
239+
LogStaleAutoApprovalRejected(this._logger, (request.ToolCall as FunctionCallContent)?.Name ?? "unknown");
240+
}
241+
242+
approvalResponses.Add(request.CreateResponse(approved: stillApprovalNotRequired));
211243
}
212244

213-
var userMessage = new ChatMessage(ChatRole.User, approvalResponses);
214-
return (messages.Concat([userMessage]), true);
245+
return (messages.Concat([new ChatMessage(ChatRole.User, approvalResponses)]), true);
215246
}
216247

217248
/// <summary>

‎dotnet/src/Microsoft.Agents.AI/ChatClient/ApprovalRequirement.cs‎

Lines changed: 36 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -31,19 +31,49 @@ internal static class ApprovalRequirement
3131
/// </summary>
3232
/// <param name="client">The decorator requesting the set, used to locate the <see cref="FunctionInvokingChatClient"/> below it in the pipeline.</param>
3333
/// <param name="options">The options for the current request, if any.</param>
34+
/// <remarks>
35+
/// Only executable functions are checked for duplicate names. A declaration may share a name with its
36+
/// implementation, and service-hosted tools are handled by the provider.
37+
/// </remarks>
38+
/// <exception cref="InvalidOperationException">Two different executable functions available to the request share a name.</exception>
3439
public static HashSet<string> GetApprovalNotRequiredToolNames(IChatClient client, ChatOptions? options)
3540
{
3641
var ficc = client.GetService<FunctionInvokingChatClient>();
3742

3843
var allTools = (options?.Tools ?? Enumerable.Empty<AITool>())
3944
.Concat(ficc?.AdditionalTools ?? Enumerable.Empty<AITool>());
4045

41-
return new HashSet<string>(
42-
allTools
43-
.OfType<AIFunction>()
44-
.Where(static f => f.GetService<ApprovalRequiredAIFunction>() is null)
45-
.Select(static f => f.Name),
46-
StringComparer.Ordinal);
46+
Dictionary<string, AIFunction> seenByName = new(StringComparer.Ordinal);
47+
HashSet<string> approvalNotRequired = new(StringComparer.Ordinal);
48+
49+
foreach (var tool in allTools)
50+
{
51+
if (tool is not AIFunction function || string.IsNullOrEmpty(function.Name))
52+
{
53+
continue;
54+
}
55+
56+
if (seenByName.TryGetValue(function.Name, out var existing))
57+
{
58+
// The same instance offered twice is not ambiguous, so it is allowed.
59+
if (!ReferenceEquals(existing, function))
60+
{
61+
throw new InvalidOperationException(
62+
$"Duplicate tool name '{function.Name}'. Tool names must be unique.");
63+
}
64+
65+
continue;
66+
}
67+
68+
seenByName[function.Name] = function;
69+
70+
if (function.GetService<ApprovalRequiredAIFunction>() is null)
71+
{
72+
approvalNotRequired.Add(function.Name);
73+
}
74+
}
75+
76+
return approvalNotRequired;
4777
}
4878

4979
/// <summary>

‎dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,24 @@ namespace Microsoft.Agents.AI;
3535
/// Developers should validate and sanitize LLM output before rendering it in HTML, executing it as code, using it in database queries,
3636
/// or passing it to any security-sensitive context. Apply defense-in-depth by combining tool approval requirements with output validation.
3737
/// </para>
38+
/// <para>
39+
/// <strong>Changing tools while approvals are outstanding:</strong> an approval request can outlive the deployment that issued it.
40+
/// A pending request records the call the model asked for, including its arguments, and waits for a human — who may not be available
41+
/// for some time, with the session suspended in the meantime. If the agent is upgraded while a request is outstanding and the tool it
42+
/// refers to has changed shape, then when the session is reloaded and the user approves, the stored arguments no longer match the tool
43+
/// and the call fails. The model is generally able to recover by calling the tool again in its new form, so this is not usually fatal,
44+
/// but developers making breaking changes to an <see cref="ApprovalRequiredAIFunction"/> — renaming or removing parameters, or changing
45+
/// their types — should expect it. Replacing a tool's implementation is a normal part of developing an agent and is not by itself a
46+
/// problem.
47+
/// </para>
48+
/// <para>
49+
/// <strong>Tools that become approval-required mid-flow:</strong> when a tool needs no approval, the framework answers on the caller's
50+
/// behalf, and it may carry that answer to the following turn. Because approval requirements are re-checked on each turn, a tool that
51+
/// has become an <see cref="ApprovalRequiredAIFunction"/> in the meantime does not inherit the earlier answer: the pending call is
52+
/// rejected rather than executed, so it never runs without a human being asked. The model is normally able to recover by issuing the
53+
/// call again, at which point it is surfaced for approval in the ordinary way. Applications that vary their tool set between turns
54+
/// should therefore expect an occasional extra round-trip while a change takes effect.
55+
/// </para>
3856
/// </remarks>
3957
public sealed partial class ChatClientAgent : AIAgent
4058
{

‎dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -210,6 +210,15 @@ public sealed class ChatClientAgentOptions
210210
/// to handle approval requests for tools that truly require human approval.
211211
/// </para>
212212
/// <para>
213+
/// A stored decision is re-checked against the tools available to the request that would act on it, and is
214+
/// only reused while the tool it refers to still does not require approval. If that tool has since become an
215+
/// <see cref="ApprovalRequiredAIFunction"/>, or is no longer available, the stored decision is discarded and
216+
/// the pending call is rejected rather than executed. The model is normally able to recover from this by
217+
/// issuing the call again, at which point it is surfaced to the caller for approval in the ordinary way.
218+
/// Callers that vary their tool set between requests should therefore expect an occasional extra round-trip,
219+
/// and an approval request for a call they had not been asked about before.
220+
/// </para>
221+
/// <para>
213222
/// Set this property to <see langword="true"/> to disable this behavior, in which case all tool calls in a
214223
/// response containing an approval-required tool are surfaced as approval requests.
215224
/// </para>

‎dotnet/src/Microsoft.Agents.AI/ChatClient/InvocableFunctionBypassingChatClient.cs‎

Lines changed: 35 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -91,9 +91,9 @@ public override async Task<ChatResponse> GetResponseAsync(
9191
return await base.GetResponseAsync(messages, options, cancellationToken).ConfigureAwait(false);
9292
}
9393

94-
messages = InjectPendingBypassedCalls(messages, session);
94+
var messagesToSend = this.PrepareBypassedCalls(messages, options, session);
9595

96-
var response = await base.GetResponseAsync(messages, options, cancellationToken).ConfigureAwait(false);
96+
var response = await base.GetResponseAsync(messagesToSend, options, cancellationToken).ConfigureAwait(false);
9797

9898
this.RemoveAndStoreBypassableInvocableCalls(response.Messages, options, session);
9999

@@ -116,7 +116,7 @@ public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseA
116116
yield break;
117117
}
118118

119-
messages = InjectPendingBypassedCalls(messages, session);
119+
messages = this.PrepareBypassedCalls(messages, options, session);
120120

121121
// Stream updates live until a surfaced (non-informational) FunctionCallContent appears, then hold the
122122
// tail so the strip/store decision can observe every call in the same batch before re-emitting.
@@ -204,14 +204,16 @@ private bool TryGetSession([NotNullWhen(true)] out AgentSession? session)
204204
private static partial void LogBypassingSkipped(ILogger logger);
205205

206206
/// <summary>
207-
/// Checks the session for invocable function calls stored on a previous turn and injects them as
208-
/// a user message containing pre-approved <see cref="ToolApprovalResponseContent"/> items appended to
209-
/// the input messages, so that <see cref="FunctionInvokingChatClient"/> reconstructs and executes them.
207+
/// Checks the session for invocable function calls stored on a previous turn and, for each one whose tool
208+
/// still needs no approval, injects it as a pre-approved <see cref="ToolApprovalResponseContent"/> appended
209+
/// to the input messages, so that <see cref="FunctionInvokingChatClient"/> reconstructs and executes it.
210+
/// A stored call whose name now requires approval, or has left the tool set, is injected as rejected
211+
/// instead, so that it is not executed.
210212
/// </summary>
211213
/// <remarks>
212214
/// <para>
213-
/// Pending calls are consumed exactly once: the session entry is removed here and is never put back, so a
214-
/// turn that fails or whose stream is abandoned drops them.
215+
/// Pending calls are kept if validation or response preparation fails. Once preparation succeeds, the session
216+
/// entry is removed and is never put back, so a failure in the inner client or an abandoned stream drops them.
215217
/// </para>
216218
/// <para>
217219
/// That is deliberate. The calls are injected as one batch and the service expects a
@@ -221,14 +223,16 @@ private bool TryGetSession([NotNullWhen(true)] out AgentSession? session)
221223
/// already run — and because a failure surfaces as an exception rather than a response, the results of
222224
/// those invocations are unrecoverable. Re-injecting the remainder would therefore still leave the batch
223225
/// incomplete while invoking already-executed functions a second time. Dropping the calls avoids the
224-
/// duplicate invocation, and matches
225-
/// <see cref="ApprovalNotRequiredFunctionBypassingChatClient"/>, which likewise never restores its entry.
226+
/// duplicate invocation.
226227
/// </para>
227228
/// </remarks>
228229
/// <param name="messages">The outgoing messages.</param>
230+
/// <param name="options">The options for the current request, used to re-check the stored calls.</param>
229231
/// <param name="session">The session holding any calls bypassed on a previous turn.</param>
230-
private static IEnumerable<ChatMessage> InjectPendingBypassedCalls(
232+
/// <returns>The messages to send to the inner client.</returns>
233+
private IEnumerable<ChatMessage> PrepareBypassedCalls(
231234
IEnumerable<ChatMessage> messages,
235+
ChatOptions? options,
232236
AgentSession session)
233237
{
234238
if (!session.StateBag.TryGetValue(
@@ -240,21 +244,35 @@ private static IEnumerable<ChatMessage> InjectPendingBypassedCalls(
240244
return messages;
241245
}
242246

243-
session.StateBag.TryRemoveValue(StateBagKey);
247+
// Stored calls are restarted using approval responses, so check current approval requirements first.
248+
var autoApprovableNames = ApprovalRequirement.GetApprovalNotRequiredToolNames(this, options);
244249

245250
List<AIContent> approvalResponses = [];
251+
246252
foreach (var call in pendingCalls)
247253
{
248-
// FunctionInvokingChatClient reconstructs and executes the call from the approval response
249-
// itself; the request is synthetic and does not need to be present in the history.
250254
var request = new ToolApprovalRequestContent(ComposeApprovalRequestId(call.CallId), call);
251-
approvalResponses.Add(request.CreateResponse(approved: true));
255+
256+
bool stillApprovalNotRequired = ApprovalRequirement.IsApprovalNotRequired(call, autoApprovableNames);
257+
258+
if (!stillApprovalNotRequired)
259+
{
260+
LogStaleBypassedCallRejected(this._logger, call.Name);
261+
}
262+
263+
// FunctionInvokingChatClient reconstructs and executes an approved call from the approval response
264+
// itself; the request is synthetic and does not need to be present in the history.
265+
approvalResponses.Add(request.CreateResponse(approved: stillApprovalNotRequired));
252266
}
253267

254-
var userMessage = new ChatMessage(ChatRole.User, approvalResponses);
255-
return messages.Concat([userMessage]);
268+
var messagesToSend = messages.Concat([new ChatMessage(ChatRole.User, approvalResponses)]);
269+
session.StateBag.TryRemoveValue(StateBagKey);
270+
return messagesToSend;
256271
}
257272

273+
[LoggerMessage(LogLevel.Warning, "A call to '{ToolName}' was bypassed for execution on a previous turn, but the tool available under that name now requires approval or is no longer available. The call is rejected rather than executed.")]
274+
private static partial void LogStaleBypassedCallRejected(ILogger logger, string toolName);
275+
258276
/// <summary>
259277
/// Composes the approval-request id for a bypassed call. The prefix deliberately differs from the
260278
/// <c>ficc_</c> prefix <see cref="FunctionInvokingChatClient"/> uses for its own approval requests, so

0 commit comments

Comments
 (0)