fix: Fix broken converstaion with orphaned toolUse

Author: Unshure

src/strands/agent/agent.py

@@ -280,7 +280,7 @@ def __init__(
                 Defaults to None.
             session_manager: Manager for handling agent sessions including conversation history and state.
                 If provided, enables session-based persistence and state management.
-            tool_executor: Definition of tool execution stragety (e.g., sequential, concurrent, etc.).
+            tool_executor: Definition of tool execution strategy (e.g., sequential, concurrent, etc.).
 
         Raises:
             ValueError: If agent id contains path separators.
@@ -816,6 +816,27 @@ def _convert_prompt_to_messages(self, prompt: AgentInput) -> Messages:
 
         messages: Messages | None = None
         if prompt is not None:
+            # Check if the latest message is toolUse
+            if len(self.messages) > 0 and any("toolUse" in content for content in self.messages[-1]["content"]):
+                # Add toolResult message after to have a valid conversation
+                tool_use_ids = [
+                    content["toolUse"]["toolUseId"] for content in self.messages[-1]["content"] if "toolUse" in content
+                ]
+                self._append_message(
+                    {
+                        "role": "user",
+                        "content": [
+                            {
+                                "toolResult": {
+                                    "toolUseId": tool_use_id,
+                                    "status": "error",
+                                    "content": [{"text": "Tool was interrupted."}],
+                                }
+                            }
+                            for tool_use_id in tool_use_ids
+                        ],
+                    }
+                )
             if isinstance(prompt, str):
                 # String input - convert to user message
                 messages = [{"role": "user", "content": [{"text": prompt}]}]

src/strands/session/repository_session_manager.py

@@ -159,6 +159,54 @@ def initialize(self, agent: "Agent", **kwargs: Any) -> None:
             # Restore the agents messages array including the optional prepend messages
             agent.messages = prepend_messages + [session_message.to_message() for session_message in session_messages]
 
+            # Fix broken session histories: https://github.com/strands-agents/sdk-python/issues/859
+            agent.messages = self._fix_broken_tool_use(agent.messages)
+
+    def _fix_broken_tool_use(self, messages: list[Message]) -> list[Message]:
+        """Add tool_result after orphaned tool_use messages.
+
+        Before 1.15.0, strands had a bug where they persisted sessions with a potentially broken messages array.
+        This method retroactively fixes that issue by adding a tool_result outside of session management. After 1.15.0,
+        this bug is no longer present.
+        """
+        for index, message in enumerate(messages):
+            # Check all but the latest message in the messages array
+            if index + 1 < len(messages):
+                if any("toolUse" in content for content in message["content"]):
+                    tool_use_ids = [
+                        content["toolUse"]["toolUseId"] for content in message["content"] if "toolUse" in content
+                    ]
+
+                    # Check if there are more messages after the current toolUse message
+                    tool_result_ids = [
+                        content["toolResult"]["toolUseId"]
+                        for content in messages[index + 1]["content"]
+                        if "toolResult" in content
+                    ]
+
+                    missing_tool_use_ids = list(set(tool_use_ids) - set(tool_result_ids))
+                    # If there area missing tool use ids, that means the messages history is broken
+                    if missing_tool_use_ids:
+                        # Create the missing toolResult content blocks
+                        missing_content_blocks = [
+                            {
+                                "toolResult": {
+                                    "toolUseId": missing_tool_use_id,
+                                    "content": [{"text": "Tool execution interrupted."}],
+                                    "status": "error",
+                                }
+                            }
+                            for missing_tool_use_id in missing_tool_use_ids
+                        ]
+
+                        if tool_result_ids:
+                            # If there were any toolResult ids, that means only some of the content blocks are missing
+                            messages[index + 1]["content"].extend(missing_content_blocks)
+                        else:
+                            # The message following the toolUse was not a toolResult, so lets insert it
+                            messages.insert(index + 1, {"role": "user", "content": missing_content_blocks})
+        return messages
+
     def sync_multi_agent(self, source: "MultiAgentBase", **kwargs: Any) -> None:
         """Serialize and update the multi-agent state into the session repository.
 

tests/strands/agent/test_agent.py

@@ -2215,3 +2215,131 @@ def test_redact_user_content(content, expected):
     agent = Agent()
     result = agent._redact_user_content(content, "REDACTED")
     assert result == expected
+
+
+def test_agent_fixes_orphaned_tool_use_on_new_prompt(mock_model, agenerator):
+    """Test that agent adds toolResult for orphaned toolUse when called with new prompt."""
+    mock_model.mock_stream.return_value = agenerator([
+        {"messageStart": {"role": "assistant"}},
+        {"contentBlockStart": {"start": {"text": ""}}},
+        {"contentBlockDelta": {"delta": {"text": "Fixed!"}}},
+        {"contentBlockStop": {}},
+        {"messageStop": {"stopReason": "end_turn"}},
+    ])
+    
+    # Start with orphaned toolUse message
+    messages = [
+        {
+            "role": "assistant",
+            "content": [{
+                "toolUse": {
+                    "toolUseId": "orphaned-123",
+                    "name": "tool_decorated",
+                    "input": {"random_string": "test"}
+                }
+            }]
+        }
+    ]
+    
+    agent = Agent(messages=messages, tools=[tool_decorated])
+    
+    # Call with new prompt should fix orphaned toolUse
+    agent("Continue conversation")
+    
+    # Should have added toolResult message
+    assert len(agent.messages) >= 3
+    assert agent.messages[1]["role"] == "user"
+    assert "toolResult" in agent.messages[1]["content"][0]
+    assert agent.messages[1]["content"][0]["toolResult"]["toolUseId"] == "orphaned-123"
+    assert agent.messages[1]["content"][0]["toolResult"]["status"] == "error"
+    assert agent.messages[1]["content"][0]["toolResult"]["content"][0]["text"] == "Tool was interrupted."
+
+
+def test_agent_fixes_multiple_orphaned_tool_uses(mock_model, agenerator):
+    """Test that agent handles multiple orphaned toolUse messages."""
+    mock_model.mock_stream.return_value = agenerator([
+        {"messageStart": {"role": "assistant"}},
+        {"contentBlockStart": {"start": {"text": ""}}},
+        {"contentBlockDelta": {"delta": {"text": "Fixed multiple!"}}},
+        {"contentBlockStop": {}},
+        {"messageStop": {"stopReason": "end_turn"}},
+    ])
+    
+    messages = [
+        {
+            "role": "assistant",
+            "content": [
+                {
+                    "toolUse": {
+                        "toolUseId": "orphaned-123",
+                        "name": "tool_decorated",
+                        "input": {"random_string": "test1"}
+                    }
+                },
+                {
+                    "toolUse": {
+                        "toolUseId": "orphaned-456",
+                        "name": "tool_decorated",
+                        "input": {"random_string": "test2"}
+                    }
+                }
+            ]
+        }
+    ]
+    
+    agent = Agent(messages=messages, tools=[tool_decorated])
+    agent("Continue")
+    
+    # Should have toolResult for both toolUse IDs
+    tool_results = agent.messages[1]["content"]
+    assert len(tool_results) == 2
+    tool_use_ids = {tr["toolResult"]["toolUseId"] for tr in tool_results}
+    assert tool_use_ids == {"orphaned-123", "orphaned-456"}
+    
+    for tool_result in tool_results:
+        assert tool_result["toolResult"]["status"] == "error"
+        assert tool_result["toolResult"]["content"][0]["text"] == "Tool was interrupted."
+
+
+def test_agent_skips_fix_for_valid_conversation(mock_model, agenerator):
+    """Test that agent doesn't modify valid toolUse/toolResult pairs."""
+    mock_model.mock_stream.return_value = agenerator([
+        {"messageStart": {"role": "assistant"}},
+        {"contentBlockStart": {"start": {"text": ""}}},
+        {"contentBlockDelta": {"delta": {"text": "No fix needed!"}}},
+        {"contentBlockStop": {}},
+        {"messageStop": {"stopReason": "end_turn"}},
+    ])
+    
+    # Valid conversation with toolUse followed by toolResult
+    messages = [
+        {
+            "role": "assistant",
+            "content": [{
+                "toolUse": {
+                    "toolUseId": "valid-123",
+                    "name": "tool_decorated",
+                    "input": {"random_string": "test"}
+                }
+            }]
+        },
+        {
+            "role": "user",
+            "content": [{
+                "toolResult": {
+                    "toolUseId": "valid-123",
+                    "status": "success",
+                    "content": [{"text": "result"}]
+                }
+            }]
+        }
+    ]
+    
+    agent = Agent(messages=messages, tools=[tool_decorated])
+    original_length = len(agent.messages)
+    
+    agent("Continue")
+    
+    # Should not have added any toolResult messages
+    # Only the new user message and assistant response should be added
+    assert len(agent.messages) == original_length + 2