Handle tool-call-only assistant history messages and guard orphaned tool results

Author: sergiobayona

lib/agents/helpers/message_extractor.rb

@@ -54,19 +54,21 @@ def extract_messages(chat, current_agent)
       end
 
       def extract_user_or_assistant_message(msg, current_agent)
-        return nil unless msg.content && !content_empty?(msg.content)
+        content_present = msg.content && !content_empty?(msg.content)
+        has_tool_calls = msg.role == :assistant && msg.tool_call? && msg.tool_calls && !msg.tool_calls.empty?
+        return nil unless content_present || has_tool_calls
 
         message = {
           role: msg.role,
-          content: msg.content
+          content: content_present ? msg.content : ""
         }
 
         if msg.role == :assistant
           # Add agent attribution for conversation continuity
           message[:agent_name] = current_agent.name if current_agent
 
           # Add tool calls if present
-          if msg.tool_call? && msg.tool_calls
+          if has_tool_calls
             # RubyLLM stores tool_calls as Hash with call_id => ToolCall object
             # Reference: RubyLLM::StreamAccumulator#tool_calls_from_stream
             message[:tool_calls] = msg.tool_calls.values.map(&:to_h)

lib/agents/runner.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "ostruct"
+require "set"
 
 module Agents
   # The execution engine that orchestrates conversations between users and agents.
@@ -272,23 +273,39 @@ def deep_copy_context(context)
     # @param context_wrapper [RunContext] Context containing conversation history
     def restore_conversation_history(chat, context_wrapper)
       history = context_wrapper.context[:conversation_history] || []
+      valid_tool_call_ids = Set.new
 
       history.each do |msg|
         next unless restorable_message?(msg)
 
+        if msg[:role].to_sym == :tool &&
+           msg[:tool_call_id] &&
+           !valid_tool_call_ids.include?(msg[:tool_call_id])
+          Agents.logger&.warn("Skipping tool message without matching assistant tool_call_id #{msg[:tool_call_id]}")
+          next
+        end
+
         message_params = build_message_params(msg)
         next unless message_params # Skip invalid messages
 
         message = RubyLLM::Message.new(**message_params)
         chat.add_message(message)
+
+        if message.role == :assistant && message_params[:tool_calls]
+          valid_tool_call_ids.merge(message_params[:tool_calls].keys)
+        end
       end
     end
 
     # Check if a message should be restored
     def restorable_message?(msg)
       role = msg[:role].to_sym
       return false unless %i[user assistant tool].include?(role)
-      return false if role != :tool && Helpers::MessageExtractor.content_empty?(msg[:content])
+
+      # Allow assistant messages that only contain tool calls (no text content)
+      tool_calls_present = role == :assistant && msg[:tool_calls] && !msg[:tool_calls].empty?
+      return false if role != :tool && !tool_calls_present &&
+                      Helpers::MessageExtractor.content_empty?(msg[:content])
 
       true
     end
@@ -297,9 +314,13 @@ def restorable_message?(msg)
     def build_message_params(msg)
       role = msg[:role].to_sym
 
+      content_value = msg[:content]
+      # Assistant tool-call messages may have empty text, but still need placeholder content
+      content_value = "" if content_value.nil? && role == :assistant && msg[:tool_calls]&.any?
+
       params = {
         role: role,
-        content: RubyLLM::Content.new(msg[:content])
+        content: RubyLLM::Content.new(content_value)
       }
 
       # Handle tool-specific parameters (Tool Results)

spec/agents/helpers/message_extractor_spec.rb

@@ -168,6 +168,46 @@
                              ])
       end
     end
+
+    context "when assistant tool calls have no text content" do
+      let(:tool_call) do
+        instance_double(RubyLLM::ToolCall,
+                        to_h: {
+                          id: "call_456",
+                          name: "test_tool",
+                          arguments: { foo: "bar" }
+                        })
+      end
+
+      let(:assistant_with_tool_only) do
+        instance_double(RubyLLM::Message,
+                        role: :assistant,
+                        content: nil,
+                        tool_call?: true,
+                        tool_calls: { "call_456" => tool_call })
+      end
+
+      let(:chat) { instance_double(RubyLLM::Chat, messages: [assistant_with_tool_only]) }
+
+      it "preserves the message and tool calls with empty string content" do
+        result = described_class.extract_messages(chat, current_agent)
+
+        expect(result).to eq([
+                               {
+                                 role: :assistant,
+                                 content: "",
+                                 agent_name: "TestAgent",
+                                 tool_calls: [
+                                   {
+                                     id: "call_456",
+                                     name: "test_tool",
+                                     arguments: { foo: "bar" }
+                                   }
+                                 ]
+                               }
+                             ])
+      end
+    end
   end
 
   describe ".content_empty?" do

spec/agents/runner_spec.rb

@@ -450,6 +450,40 @@
         end
       end
 
+      context "with assistant tool calls that have empty content" do
+        let(:context_with_tool_only_assistant) do
+          {
+            conversation_history: [
+              { role: :user, content: "Trigger a tool" },
+              {
+                role: :assistant,
+                content: "",
+                tool_calls: [{ id: "call_blank", name: "do_something", arguments: {} }]
+              },
+              { role: :tool, content: "Done", tool_call_id: "call_blank" }
+            ]
+          }
+        end
+
+        before do
+          stub_simple_chat("All set")
+        end
+
+        it "restores assistant tool call messages even without text" do
+          result = runner.run(agent, "Thanks", context: context_with_tool_only_assistant)
+
+          expect(result.success?).to be true
+
+          assistant_with_tools = result.messages.find do |msg|
+            msg[:role] == :assistant && msg[:tool_calls]&.any?
+          end
+
+          expect(assistant_with_tools).not_to be_nil
+          expect(assistant_with_tools[:content]).to eq("")
+          expect(assistant_with_tools[:tool_calls].first[:id]).to eq("call_blank")
+        end
+      end
+
       it "restores tool_calls on assistant messages" do
         # As of commit 1cfe99e, tool_calls ARE restored on assistant messages
         # because OpenAI/Anthropic APIs require tool result messages to be