fix(routing): force tool_choice=required in OneStepForwardReasoner to eliminate format drift

Author: Yanan Wang

src/Infrastructure/BotSharp.Core/Routing/Reasoning/OneStepForwardReasoner.cs

@@ -15,6 +15,7 @@ limitations under the License.
 ******************************************************************************/
 
 using BotSharp.Abstraction.Infrastructures.Enums;
+using BotSharp.Abstraction.MLTasks;
 using BotSharp.Abstraction.Routing.Models;
 using BotSharp.Abstraction.Routing.Reasoning;
 using BotSharp.Abstraction.Templating;
@@ -61,14 +62,15 @@ public async Task<FunctionCallFromLlm> GetNextInstruction(Agent router, string m
                 MessageId = messageId
             }
         };
-        var response = await completion.GetChatCompletions(router, dialogs);
 
-        // Due to format drift, LLMs may complete with finishReason=function_call (instruction in FunctionArgs)
-        // or finishReason=stop (instruction serialized as JSON in Content).
-        // Use FunctionArgs ?? Content to be compatible with both cases.
-        var inst = (response.FunctionArgs ?? response.Content).JsonContent<FunctionCallFromLlm>();
-        var routingCtx = _services.GetRequiredService<IRoutingContext>();
-        _logger.LogInformation($"[OneStepForwardReasoner] ConversationId: {routingCtx.ConversationId}, MessageId: {messageId}, Next instruction: {response.FunctionArgs ?? response.Content}");
+        // Force tool_choice=required so the LLM always returns the instruction as a function call,
+        // eliminating format drift where the LLM completes with finishReason=stop and returns
+        // free text or JSON in Content instead of a structured function call.
+        var response = await GetChatCompletionsWithScopedState(completion, router, dialogs, "tool_choice", "required");
+
+        var inst = response.FunctionArgs?.JsonContent<FunctionCallFromLlm>();
+        _logger.LogInformation("[OneStepForwardReasoner] ConversationId: {ConversationId}, MessageId: {MessageId}, Next instruction: {Instruction}",
+            _services.GetRequiredService<IRoutingContext>().ConversationId, messageId, response.FunctionArgs);
 
         // Fix LLM malformed response
         await ReasonerHelper.FixMalformedResponse(_services, inst);
@@ -107,6 +109,30 @@ public async Task<bool> AgentExecuted(Agent router, FunctionCallFromLlm inst, Ro
         return true;
     }
 
+    /// <summary>
+    /// Runs chat completion with a scoped conversation state that is set before the call
+    /// and guaranteed to be removed afterwards, even if the completion throws.
+    /// </summary>
+    private async Task<RoleDialogModel> GetChatCompletionsWithScopedState(
+        IChatCompletion completion,
+        Agent agent,
+        List<RoleDialogModel> dialogs,
+        string stateKey,
+        string stateValue)
+    {
+        var states = _services.GetRequiredService<IConversationStateService>();
+        states.SetState(stateKey, stateValue, source: StateSource.Application);
+
+        try
+        {
+            return await completion.GetChatCompletions(agent, dialogs);
+        }
+        finally
+        {
+            states.RemoveState(stateKey);
+        }
+    }
+
     private string GetNextStepPrompt(Agent router)
     {
         var template = router.Templates.First(x => x.Name == "reasoner.one-step-forward").Content;

src/Plugins/BotSharp.Plugin.OpenAI/Providers/Chat/ChatCompletionProvider.Chat.cs

@@ -405,6 +405,12 @@ private async Task<RoleDialogModel> InnerGetChatCompletionsStreamingAsync(Agent
             }
         }
 
+        // Apply tool_choice only when tools are present; tool_choice is rejected by the API otherwise.
+        if (!options.Tools.IsNullOrEmpty() && _state.GetState("tool_choice") == "required")
+        {
+            options.ToolChoice = ChatToolChoice.CreateRequiredChoice();
+        }
+
         if (!string.IsNullOrEmpty(agent.Knowledges))
         {
             messages.Add(new SystemChatMessage(agent.Knowledges));