fix: Properly handle prompt=None & avoid agent hanging

bedrock.py now catches all exceptions in _stream so it no longer hangs when invalid content is passed.

In addition, since we don't allow agent(None), go ahead and validate that none is not passed throughout our agent calls.

Author: zastrowm

pyproject.toml

@@ -234,8 +234,8 @@ test-integ = [
     "hatch test tests_integ {args}"
 ]
 prepare = [
-    "hatch fmt --linter",
     "hatch fmt --formatter",
+    "hatch fmt --linter",
     "hatch run test-lint",
     "hatch test --all"
 ]

src/strands/agent/agent.py

@@ -367,6 +367,9 @@ def __call__(self, prompt: Union[str, list[ContentBlock]], **kwargs: Any) -> Age
                 - message: The final message from the model
                 - metrics: Performance metrics from the event loop
                 - state: The final state of the event loop
+
+        Raises:
+            ValueError: If prompt is None.
         """
 
         def execute() -> AgentResult:
@@ -393,6 +396,9 @@ async def invoke_async(self, prompt: Union[str, list[ContentBlock]], **kwargs: A
                 - message: The final message from the model
                 - metrics: Performance metrics from the event loop
                 - state: The final state of the event loop
+
+        Raises:
+            ValueError: If prompt is None.
         """
         events = self.stream_async(prompt, **kwargs)
         async for event in events:
@@ -452,8 +458,8 @@ async def structured_output_async(
 
             # add the prompt as the last message
             if prompt:
-                content: list[ContentBlock] = [{"text": prompt}] if isinstance(prompt, str) else prompt
-                self._append_message({"role": "user", "content": content})
+                message = self._standardize_prompt(prompt)
+                self._append_message(message)
 
             events = self.model.structured_output(output_model, self.messages, system_prompt=self.system_prompt)
             async for event in events:
@@ -487,6 +493,7 @@ async def stream_async(self, prompt: Union[str, list[ContentBlock]], **kwargs: A
             - And other event data provided by the callback handler
 
         Raises:
+            ValueError: If prompt is None.
             Exception: Any exceptions from the agent invocation will be propagated to the caller.
 
         Example:
@@ -498,8 +505,7 @@ async def stream_async(self, prompt: Union[str, list[ContentBlock]], **kwargs: A
         """
         callback_handler = kwargs.get("callback_handler", self.callback_handler)
 
-        content: list[ContentBlock] = [{"text": prompt}] if isinstance(prompt, str) else prompt
-        message: Message = {"role": "user", "content": content}
+        message = self._standardize_prompt(prompt)
 
         self.trace_span = self._start_agent_trace_span(message)
         with trace_api.use_span(self.trace_span):
@@ -561,6 +567,15 @@ async def _run_loop(
             self.conversation_manager.apply_management(self)
             self.hooks.invoke_callbacks(AfterInvocationEvent(agent=self))
 
+    def _standardize_prompt(self, prompt: Union[str, list[ContentBlock]]) -> Message:
+        """Convert the prompt into a Message, validating it along the way."""
+        if prompt is None:
+            raise ValueError("User prompt must not be None")
+
+        content: list[ContentBlock] = [{"text": prompt}] if isinstance(prompt, str) else prompt
+        message: Message = {"role": "user", "content": content}
+        return message
+
     async def _execute_event_loop_cycle(self, invocation_state: dict[str, Any]) -> AsyncGenerator[dict[str, Any], None]:
         """Execute the event loop cycle with retry logic for context window limits.
 

src/strands/models/bedrock.py

@@ -418,14 +418,14 @@ def _stream(
             ContextWindowOverflowException: If the input exceeds the model's context window.
             ModelThrottledException: If the model service is throttling requests.
         """
-        logger.debug("formatting request")
-        request = self.format_request(messages, tool_specs, system_prompt)
-        logger.debug("request=<%s>", request)
+        try:
+            logger.debug("formatting request")
+            request = self.format_request(messages, tool_specs, system_prompt)
+            logger.debug("request=<%s>", request)
 
-        logger.debug("invoking model")
-        streaming = self.config.get("streaming", True)
+            logger.debug("invoking model")
+            streaming = self.config.get("streaming", True)
 
-        try:
             logger.debug("got response from model")
             if streaming:
                 response = self.client.converse_stream(**request)

tests/strands/agent/test_agent.py

@@ -750,6 +750,24 @@ async def test_agent__call__in_async_context(mock_model, agent, agenerator):
     assert tru_message == exp_message
 
 
+@pytest.mark.asyncio
+async def test_agent_invocations_prompt_validation(agent, alist):
+    with pytest.raises(ValueError):
+        await agent.invoke_async(prompt=None)
+
+    with pytest.raises(ValueError):
+        await agent(prompt=None)
+
+    with pytest.raises(ValueError):
+        await alist(agent.stream_async(prompt=None))
+
+    with pytest.raises(ValueError):
+        await agent.structured_output(type(user), prompt=None)
+
+    with pytest.raises(ValueError):
+        await agent.structured_output_async(type(user), prompt=None)
+
+
 @pytest.mark.asyncio
 async def test_agent_invoke_async(mock_model, agent, agenerator):
     mock_model.mock_stream.return_value = agenerator(

tests/strands/models/test_bedrock.py

@@ -419,6 +419,15 @@ async def test_stream_throttling_exception_from_event_stream_error(bedrock_clien
     )
 
 
+@pytest.mark.asyncio
+async def test_stream_with_invalid_content_throws(bedrock_client, model, alist):
+    # We used to hang on None, so ensure we don't regress: https://github.com/strands-agents/sdk-python/issues/642
+    messages = [{"role": "user", "content": None}]
+
+    with pytest.raises(TypeError):
+        await alist(model.stream(messages))
+
+
 @pytest.mark.asyncio
 async def test_stream_throttling_exception_from_general_exception(bedrock_client, model, messages, alist):
     error_message = "ThrottlingException: Rate exceeded for ConverseStream"