feat: add system_prompt to Agent run parameters (#9778)

* enhancement: add system_prompt to Agent run parameters

* add reno

* add test

Author: tstadel

haystack/components/agents/agent.py

@@ -255,6 +255,7 @@ def _initialize_fresh_execution(
         messages: list[ChatMessage],
         streaming_callback: Optional[StreamingCallbackT],
         requires_async: bool,
+        system_prompt: Optional[str] = None,
         **kwargs,
     ) -> _ExecutionContext:
         """
@@ -263,10 +264,12 @@ def _initialize_fresh_execution(
         :param messages: List of ChatMessage objects to start the agent with.
         :param streaming_callback: Optional callback for streaming responses.
         :param requires_async: Whether the agent run requires asynchronous execution.
+        :param system_prompt: System prompt for the agent. If provided, it overrides the default system prompt.
         :param kwargs: Additional data to pass to the State used by the Agent.
         """
-        if self.system_prompt is not None:
-            messages = [ChatMessage.from_system(self.system_prompt)] + messages
+        system_prompt = system_prompt or self.system_prompt
+        if system_prompt is not None:
+            messages = [ChatMessage.from_system(system_prompt)] + messages
 
         if all(m.is_from(ChatRole.SYSTEM) for m in messages):
             logger.warning("All messages provided to the Agent component are system messages. This is not recommended.")
@@ -443,6 +446,7 @@ def run(
         *,
         break_point: Optional[AgentBreakpoint] = None,
         snapshot: Optional[AgentSnapshot] = None,
+        system_prompt: Optional[str] = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         """
@@ -455,6 +459,7 @@ def run(
             for "tool_invoker".
         :param snapshot: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains
             the relevant information to restart the Agent execution from where it left off.
+        :param system_prompt: System prompt for the agent. If provided, it overrides the default system prompt.
         :param kwargs: Additional data to pass to the State schema used by the Agent.
             The keys must match the schema defined in the Agent's `state_schema`.
         :returns:
@@ -482,7 +487,11 @@ def run(
             )
         else:
             exe_context = self._initialize_fresh_execution(
-                messages=messages, streaming_callback=streaming_callback, requires_async=False, **kwargs
+                messages=messages,
+                streaming_callback=streaming_callback,
+                requires_async=False,
+                system_prompt=system_prompt,
+                **kwargs,
             )
 
         with self._create_agent_span() as span:
@@ -558,6 +567,7 @@ async def run_async(
         *,
         break_point: Optional[AgentBreakpoint] = None,
         snapshot: Optional[AgentSnapshot] = None,
+        system_prompt: Optional[str] = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         """
@@ -574,6 +584,7 @@ async def run_async(
             for "tool_invoker".
         :param snapshot: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains
             the relevant information to restart the Agent execution from where it left off.
+        :param system_prompt: System prompt for the agent. If provided, it overrides the default system prompt.
         :param kwargs: Additional data to pass to the State schema used by the Agent.
             The keys must match the schema defined in the Agent's `state_schema`.
         :returns:
@@ -601,7 +612,11 @@ async def run_async(
             )
         else:
             exe_context = self._initialize_fresh_execution(
-                messages=messages, streaming_callback=streaming_callback, requires_async=False, **kwargs
+                messages=messages,
+                streaming_callback=streaming_callback,
+                requires_async=False,
+                system_prompt=system_prompt,
+                **kwargs,
             )
 
         with self._create_agent_span() as span:

releasenotes/notes/add-system_prompt-to-agent-run-params-5423944e1eebb572.yaml

@@ -0,0 +1,4 @@
+---
+enhancements:
+  - |
+    Added `system_prompt` to agent run parameters to enhance customization and control over agent behavior.

test/components/agents/test_agent.py

@@ -732,6 +732,17 @@ def test_run_with_system_prompt(self, weather_tool):
         response = agent.run([ChatMessage.from_user("What is the weather in Berlin?")])
         assert response["messages"][0].text == "This is a system prompt."
 
+    def test_run_with_system_prompt_run_param(self, weather_tool):
+        chat_generator = MockChatGeneratorWithoutRunAsync()
+        agent = Agent(
+            chat_generator=chat_generator, tools=[weather_tool], system_prompt="This is the init system prompt."
+        )
+        agent.warm_up()
+        response = agent.run(
+            [ChatMessage.from_user("What is the weather in Berlin?")], system_prompt="This is the run system prompt."
+        )
+        assert response["messages"][0].text == "This is the run system prompt."
+
     def test_run_not_warmed_up(self, weather_tool):
         chat_generator = MockChatGeneratorWithoutRunAsync()
         chat_generator.warm_up = MagicMock()