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

@@ -4,7 +4,7 @@
 from typing import TYPE_CHECKING, Any, Optional
 
 from ..agent.state import AgentState
-from ..types.content import Message
+from ..types.content import ContentBlock, Message
 from ..types.exceptions import SessionException
 from ..types.session import (
     Session,
@@ -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: list[ContentBlock] = [
+                            {
+                                "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,125 @@ 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(model=mock_model, 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(model=mock_model, 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(model=mock_model, 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

tests/strands/session/test_repository_session_manager.py

@@ -233,3 +233,153 @@ def test_initialize_multi_agent_existing(session_manager, mock_multi_agent):
 
     # Verify deserialize_state was called with existing state
     mock_multi_agent.deserialize_state.assert_called_once_with(existing_state)
+
+
+def test_fix_broken_tool_use_adds_missing_tool_results(session_manager):
+    """Test that _fix_broken_tool_use adds missing toolResult messages."""
+    # Messages with orphaned toolUse
+    broken_messages = [
+        {
+            "role": "assistant",
+            "content": [{"toolUse": {"toolUseId": "orphaned-123", "name": "test_tool", "input": {"input": "test"}}}],
+        },
+        {"role": "user", "content": [{"text": "Some other message"}]},
+    ]
+
+    fixed_messages = session_manager._fix_broken_tool_use(broken_messages)
+
+    # Should insert toolResult message between toolUse and other message
+    assert len(fixed_messages) == 3
+    assert fixed_messages[1]["role"] == "user"
+    assert "toolResult" in fixed_messages[1]["content"][0]
+    assert fixed_messages[1]["content"][0]["toolResult"]["toolUseId"] == "orphaned-123"
+    assert fixed_messages[1]["content"][0]["toolResult"]["status"] == "error"
+    assert fixed_messages[1]["content"][0]["toolResult"]["content"][0]["text"] == "Tool execution interrupted."
+
+
+def test_fix_broken_tool_use_extends_partial_tool_results(session_manager):
+    """Test fixing messages where some toolResults are missing."""
+    messages = [
+        {
+            "role": "assistant",
+            "content": [
+                {"toolUse": {"toolUseId": "complete-123", "name": "test_tool", "input": {"input": "test1"}}},
+                {"toolUse": {"toolUseId": "missing-456", "name": "test_tool", "input": {"input": "test2"}}},
+            ],
+        },
+        {
+            "role": "user",
+            "content": [
+                {"toolResult": {"toolUseId": "complete-123", "status": "success", "content": [{"text": "result"}]}}
+            ],
+        },
+    ]
+
+    fixed_messages = session_manager._fix_broken_tool_use(messages)
+
+    # Should add missing toolResult to existing message
+    assert len(fixed_messages) == 2
+    assert len(fixed_messages[1]["content"]) == 2
+
+    tool_use_ids = {tr["toolResult"]["toolUseId"] for tr in fixed_messages[1]["content"]}
+    assert tool_use_ids == {"complete-123", "missing-456"}
+
+    # Check the added toolResult has correct properties
+    missing_result = next(tr for tr in fixed_messages[1]["content"] if tr["toolResult"]["toolUseId"] == "missing-456")
+    assert missing_result["toolResult"]["status"] == "error"
+    assert missing_result["toolResult"]["content"][0]["text"] == "Tool execution interrupted."
+
+
+def test_fix_broken_tool_use_handles_multiple_orphaned_tools(session_manager):
+    """Test fixing multiple orphaned toolUse messages."""
+    messages = [
+        {
+            "role": "assistant",
+            "content": [
+                {"toolUse": {"toolUseId": "orphaned-123", "name": "test_tool", "input": {"input": "test1"}}},
+                {"toolUse": {"toolUseId": "orphaned-456", "name": "test_tool", "input": {"input": "test2"}}},
+            ],
+        },
+        {"role": "user", "content": [{"text": "Next message"}]},
+    ]
+
+    fixed_messages = session_manager._fix_broken_tool_use(messages)
+
+    # Should insert message with both toolResults
+    assert len(fixed_messages) == 3
+    assert len(fixed_messages[1]["content"]) == 2
+
+    tool_use_ids = {tr["toolResult"]["toolUseId"] for tr in fixed_messages[1]["content"]}
+    assert tool_use_ids == {"orphaned-123", "orphaned-456"}
+
+
+def test_fix_broken_tool_use_preserves_valid_messages(session_manager):
+    """Test that valid message sequences are not modified."""
+    valid_messages = [
+        {
+            "role": "assistant",
+            "content": [{"toolUse": {"toolUseId": "valid-123", "name": "test_tool", "input": {"input": "test"}}}],
+        },
+        {
+            "role": "user",
+            "content": [
+                {"toolResult": {"toolUseId": "valid-123", "status": "success", "content": [{"text": "result"}]}}
+            ],
+        },
+    ]
+
+    fixed_messages = session_manager._fix_broken_tool_use(valid_messages)
+
+    # Should remain unchanged
+    assert fixed_messages == valid_messages
+
+
+def test_fix_broken_tool_use_ignores_last_message(session_manager):
+    """Test that orphaned toolUse in the last message is not fixed."""
+    messages = [
+        {"role": "user", "content": [{"text": "Hello"}]},
+        {
+            "role": "assistant",
+            "content": [
+                {"toolUse": {"toolUseId": "last-message-123", "name": "test_tool", "input": {"input": "test"}}}
+            ],
+        },
+    ]
+
+    fixed_messages = session_manager._fix_broken_tool_use(messages)
+
+    # Should remain unchanged since toolUse is in last message
+    assert fixed_messages == messages
+
+
+def test_initialize_agent_applies_fix_broken_tool_use(session_manager):
+    """Test that initialize applies the fix_broken_tool_use method."""
+    agent = Agent(agent_id="test-agent")
+
+    # Create session agent first
+    session_agent = SessionAgent(
+        agent_id="test-agent", state={}, conversation_manager_state=SlidingWindowConversationManager().get_state()
+    )
+    session_manager.session_repository.create_agent("test-session", session_agent)
+
+    # Add broken messages to session
+    broken_message = SessionMessage(
+        message={
+            "role": "assistant",
+            "content": [{"toolUse": {"toolUseId": "broken-123", "name": "test_tool", "input": {"input": "test"}}}],
+        },
+        message_id=0,
+    )
+    session_manager.session_repository.create_message("test-session", "test-agent", broken_message)
+
+    follow_up_message = SessionMessage(message={"role": "user", "content": [{"text": "Some message"}]}, message_id=1)
+    session_manager.session_repository.create_message("test-session", "test-agent", follow_up_message)
+
+    # Initialize agent - should apply fix
+    session_manager.initialize(agent)
+
+    # Check that fix was applied
+    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"] == "broken-123"