feat: enforce message history starts with user message

Add validation in UserPromptNode to raise UserError if message history starts with ModelResponse, ensuring conversations begin with a user message (ModelRequest)

Include comprehensive tests for invalid history, valid history, empty history, multiple messages, and validation after message cleaning to prevent issues with malformed conversation logs

Author: pavan

pydantic_ai_slim/pydantic_ai/_agent_graph.py

@@ -216,6 +216,12 @@ async def run(  # noqa: C901
         ctx.state.message_history = messages
         ctx.deps.new_message_index = len(messages)
 
+        # Validate that message history starts with a user message
+        if messages and isinstance(messages[0], _messages.ModelResponse):
+            raise exceptions.UserError(
+                'Message history cannot start with a `ModelResponse`. Conversations must begin with a user message.'
+            )
+
         if self.deferred_tool_results is not None:
             return await self._handle_deferred_tool_results(self.deferred_tool_results, messages, ctx)
 

tests/test_agent.py

@@ -6125,3 +6125,108 @@ def llm(messages: list[ModelMessage], _info: AgentInfo) -> ModelResponse:
             ]
         )
         assert run.all_messages_json().startswith(b'[{"parts":[{"content":"Hello",')
+
+
+def test_message_history_cannot_start_with_model_response():
+    """Test that message history starting with ModelResponse raises UserError."""
+
+    def simple_response(_messages: list[ModelMessage], _info: AgentInfo) -> ModelResponse:
+        return ModelResponse(parts=[TextPart(content='Final response')])  # pragma: no cover
+
+    agent = Agent(FunctionModel(simple_response))
+
+    invalid_history = [
+        ModelResponse(parts=[TextPart(content='ai response')]),
+    ]
+
+    with pytest.raises(
+        UserError,
+        match='Message history cannot start with a `ModelResponse`.',
+    ):
+        agent.run_sync('hello', message_history=invalid_history)
+
+
+async def test_message_history_starts_with_model_request():
+    """Test that valid history starting with ModelRequest works correctly."""
+
+    def llm(messages: list[ModelMessage], _info: AgentInfo) -> ModelResponse:
+        return ModelResponse(parts=[TextPart('ok here is text')])
+
+    agent = Agent(FunctionModel(llm))
+
+    valid_history = [
+        ModelRequest(parts=[UserPromptPart(content='Hello')]),
+        ModelResponse(parts=[TextPart(content='Hi there!')]),
+    ]
+
+    # Should not raise error - valid history starting with ModelRequest
+    async with agent.iter('How are you?', message_history=valid_history) as run:
+        async for _ in run:
+            pass
+        # Verify messages are processed correctly
+        all_messages = run.all_messages()
+        assert len(all_messages) >= 3  # History + new request + response
+        assert isinstance(all_messages[0], ModelRequest)  # First message is ModelRequest
+
+
+async def test_empty_message_history_is_valid():
+    """Test that empty message history works fine."""
+
+    def llm(messages: list[ModelMessage], _info: AgentInfo) -> ModelResponse:
+        return ModelResponse(parts=[TextPart('response text')])
+
+    agent = Agent(FunctionModel(llm))
+
+    # Empty history should work - should not raise error
+    async with agent.iter('hello', message_history=[]) as run:
+        async for _ in run:
+            pass
+        all_messages = run.all_messages()
+        assert len(all_messages) >= 2  # Request + response
+        assert isinstance(all_messages[0], ModelRequest)
+
+
+async def test_message_history_with_multiple_messages():
+    """Test that history with multiple messages starting correctly works."""
+
+    def llm(messages: list[ModelMessage], _info: AgentInfo) -> ModelResponse:
+        return ModelResponse(parts=[TextPart('final response')])
+
+    agent = Agent(FunctionModel(llm))
+
+    valid_history = [
+        ModelRequest(parts=[UserPromptPart(content='First')]),
+        ModelResponse(parts=[TextPart(content='Response 1')]),
+        ModelRequest(parts=[UserPromptPart(content='Second')]),
+        ModelResponse(parts=[TextPart(content='Response 2')]),
+    ]
+
+    async with agent.iter('Third message', message_history=valid_history) as run:
+        async for _ in run:
+            pass
+        # Verify the history is preserved and new message is added
+        all_messages = run.all_messages()
+        assert len(all_messages) >= 5  # 4 from history + at least 1 new
+        assert isinstance(all_messages[0], ModelRequest)
+        assert isinstance(all_messages[-1], ModelResponse)
+
+
+def test_validation_happens_after_cleaning():
+    """Test that validation catches issues even after message cleaning."""
+
+    def simple_response(_messages: list[ModelMessage], _info: AgentInfo) -> ModelResponse:
+        return ModelResponse(parts=[TextPart(content='Final response')])  # pragma: no cover
+
+    agent = Agent(FunctionModel(simple_response))
+
+    # Even if cleaning merges messages, first should still be checked
+    invalid_history = [
+        ModelResponse(parts=[TextPart(content='response 1')]),
+        ModelResponse(parts=[TextPart(content='response 2')]),  # Would be merged
+    ]
+
+    with pytest.raises(
+        UserError,
+        match='Message history cannot start with a `ModelResponse`.',
+    ):
+        agent.run_sync('hello', message_history=invalid_history)