Ignore dynamic instructions returning an empty string (#1961)

Co-authored-by: giacbrd <giacomo.brd@gmail.com>

Author: giacbrd

docs/agents.md

@@ -701,6 +701,8 @@ _(This example is complete, it can be run "as is")_
 
 You can also dynamically change the instructions for an agent by using the `@agent.instructions` decorator.
 
+Note that returning an empty string will result in no instruction message added.
+
 ```python {title="dynamic_instructions.py"}
 from datetime import date
 

pydantic_ai_slim/pydantic_ai/agent.py

@@ -669,10 +669,11 @@ async def get_instructions(run_context: RunContext[AgentDepsT]) -> str | None:
             if self._instructions is None and not self._instructions_functions:
                 return None
 
-            instructions = self._instructions or ''
+            instructions = [self._instructions] if self._instructions else []
             for instructions_runner in self._instructions_functions:
-                instructions += '\n' + await instructions_runner.run(run_context)
-            return instructions.strip()
+                instructions.append(await instructions_runner.run(run_context))
+            concatenated_instructions = '\n'.join(instruction for instruction in instructions if instruction)
+            return concatenated_instructions.strip() if concatenated_instructions else None
 
         # Copy the function tools so that retry state is agent-run-specific
         # Note that the retry count is reset to 0 when this happens due to the `default=0` and `init=False`.

tests/test_agent.py

@@ -2425,6 +2425,10 @@ def test_instructions_raise_error_when_instructions_is_set():
     def instructions() -> str:
         return 'An instructions!'
 
+    @agent.instructions
+    def empty_instructions() -> str:
+        return ''
+
     result = agent.run_sync('Hello')
     assert result.all_messages()[0] == snapshot(
         ModelRequest(
@@ -2512,7 +2516,10 @@ def test_instructions_parameter_with_sequence():
     def instructions() -> str:
         return 'You are a potato.'
 
-    agent = Agent('test', instructions=('You are a helpful assistant.', instructions))
+    def empty_instructions() -> str:
+        return ''
+
+    agent = Agent('test', instructions=('You are a helpful assistant.', empty_instructions, instructions))
     result = agent.run_sync('Hello')
     assert result.all_messages()[0] == snapshot(
         ModelRequest(