Add instructions parameter (#1360)

Co-authored-by: David Montague <35119617+dmontagu@users.noreply.github.com>

Author: Kludex

docs/agents.md

@@ -123,6 +123,8 @@ async def main():
     [
         UserPromptNode(
             user_prompt='What is the capital of France?',
+            instructions=None,
+            instructions_functions=[],
             system_prompts=(),
             system_prompt_functions=[],
             system_prompt_dynamic_functions={},
@@ -136,6 +138,7 @@ async def main():
                         part_kind='user-prompt',
                     )
                 ],
+                instructions=None,
                 kind='request',
             )
         ),
@@ -184,6 +187,8 @@ async def main():
         [
             UserPromptNode(
                 user_prompt='What is the capital of France?',
+                instructions=None,
+                instructions_functions=[],
                 system_prompts=(),
                 system_prompt_functions=[],
                 system_prompt_dynamic_functions={},
@@ -197,6 +202,7 @@ async def main():
                             part_kind='user-prompt',
                         )
                     ],
+                    instructions=None,
                     kind='request',
                 )
             ),
@@ -612,6 +618,14 @@ Running `pyright` would identify the same issues.
 
 System prompts might seem simple at first glance since they're just strings (or sequences of strings that are concatenated), but crafting the right system prompt is key to getting the model to behave as you want.
 
+!!! tip
+    For most use cases, you should use `instructions` instead of "system prompts".
+
+    If you know what you are doing though and want to preserve system prompt messages in the message history sent to the
+    LLM in subsequent completions requests, you can achieve this using the `system_prompt` argument/decorator.
+
+    See the section below on [Instructions](#instructions) for more information.
+
 Generally, system prompts fall into two categories:
 
 1. **Static system prompts**: These are known when writing the code and can be defined via the `system_prompt` parameter of the [`Agent` constructor][pydantic_ai.Agent.__init__].
@@ -655,6 +669,36 @@ print(result.output)
 
 _(This example is complete, it can be run "as is")_
 
+## Instructions
+
+Instructions are similar to system prompts. The main difference is that when an explicit `message_history` is provided
+in a call to `Agent.run` and similar methods, _instructions_ from any existing messages in the history are not included
+in the request to the model — only the instructions of the _current_ agent are included.
+
+You should use:
+
+- `instructions` when you want your request to the model to only include system prompts for the _current_ agent
+- `system_prompt` when you want your request to the model to _retain_ the system prompts used in previous requests (possibly made using other agents)
+
+In general, we recommend using `instructions` instead of `system_prompt` unless you have a specific reason to use `system_prompt`.
+
+```python {title="instructions.py"}
+from pydantic_ai import Agent
+
+agent = Agent(
+    'openai:gpt-4o',
+    instructions='You are a helpful assistant that can answer questions and help with tasks.',  # (1)!
+)
+
+result = agent.run_sync('What is the capital of France?')
+print(result.output)
+#> Paris
+```
+
+1. This will be the only instructions for this agent.
+
+_(This example is complete, it can be run "as is")_
+
 ## Reflection and self-correction
 
 Validation errors from both function tool parameter validation and [structured output validation](output.md#structured-output) can be passed back to the model with a request to retry.
@@ -749,6 +793,7 @@ with capture_run_messages() as messages:  # (2)!
                         part_kind='user-prompt',
                     )
                 ],
+                instructions=None,
                 kind='request',
             ),
             ModelResponse(
@@ -774,6 +819,7 @@ with capture_run_messages() as messages:  # (2)!
                         part_kind='retry-prompt',
                     )
                 ],
+                instructions=None,
                 kind='request',
             ),
             ModelResponse(

docs/api/models/function.md

@@ -31,6 +31,7 @@ async def model_function(
                     part_kind='user-prompt',
                 )
             ],
+            instructions=None,
             kind='request',
         )
     ]

docs/message-history.md

@@ -54,6 +54,7 @@ print(result.all_messages())
                 part_kind='user-prompt',
             ),
         ],
+        instructions=None,
         kind='request',
     ),
     ModelResponse(
@@ -100,6 +101,7 @@ async def main():
                         part_kind='user-prompt',
                     ),
                 ],
+                instructions=None,
                 kind='request',
             )
         ]
@@ -130,6 +132,7 @@ async def main():
                         part_kind='user-prompt',
                     ),
                 ],
+                instructions=None,
                 kind='request',
             ),
             ModelResponse(
@@ -188,6 +191,7 @@ print(result2.all_messages())
                 part_kind='user-prompt',
             ),
         ],
+        instructions=None,
         kind='request',
     ),
     ModelResponse(
@@ -209,6 +213,7 @@ print(result2.all_messages())
                 part_kind='user-prompt',
             )
         ],
+        instructions=None,
         kind='request',
     ),
     ModelResponse(
@@ -314,6 +319,7 @@ print(result2.all_messages())
                 part_kind='user-prompt',
             ),
         ],
+        instructions=None,
         kind='request',
     ),
     ModelResponse(
@@ -335,6 +341,7 @@ print(result2.all_messages())
                 part_kind='user-prompt',
             )
         ],
+        instructions=None,
         kind='request',
     ),
     ModelResponse(

docs/tools.md

@@ -82,6 +82,7 @@ print(dice_result.all_messages())
                 part_kind='user-prompt',
             ),
         ],
+        instructions=None,
         kind='request',
     ),
     ModelResponse(
@@ -107,6 +108,7 @@ print(dice_result.all_messages())
                 part_kind='tool-return',
             )
         ],
+        instructions=None,
         kind='request',
     ),
     ModelResponse(
@@ -132,6 +134,7 @@ print(dice_result.all_messages())
                 part_kind='tool-return',
             )
         ],
+        instructions=None,
         kind='request',
     ),
     ModelResponse(

pydantic_ai_slim/pydantic_ai/_agent_graph.py

@@ -125,6 +125,9 @@ def is_agent_node(
 class UserPromptNode(AgentNode[DepsT, NodeRunEndT]):
     user_prompt: str | Sequence[_messages.UserContent] | None
 
+    instructions: str | None
+    instructions_functions: list[_system_prompt.SystemPromptRunner[DepsT]]
+
     system_prompts: tuple[str, ...]
     system_prompt_functions: list[_system_prompt.SystemPromptRunner[DepsT]]
     system_prompt_dynamic_functions: dict[str, _system_prompt.SystemPromptRunner[DepsT]]
@@ -166,6 +169,7 @@ async def _prepare_messages(
                 ctx_messages.used = True
 
         parts: list[_messages.ModelRequestPart] = []
+        instructions = await self._instructions(run_context)
         if message_history:
             # Shallow copy messages
             messages.extend(message_history)
@@ -176,7 +180,7 @@ async def _prepare_messages(
 
         if user_prompt is not None:
             parts.append(_messages.UserPromptPart(user_prompt))
-        return messages, _messages.ModelRequest(parts)
+        return messages, _messages.ModelRequest(parts, instructions=instructions)
 
     async def _reevaluate_dynamic_prompts(
         self, messages: list[_messages.ModelMessage], run_context: RunContext[DepsT]
@@ -206,6 +210,15 @@ async def _sys_parts(self, run_context: RunContext[DepsT]) -> list[_messages.Mod
                 messages.append(_messages.SystemPromptPart(prompt))
         return messages
 
+    async def _instructions(self, run_context: RunContext[DepsT]) -> str | None:
+        if self.instructions is None and not self.instructions_functions:
+            return None
+
+        instructions = self.instructions or ''
+        for instructions_runner in self.instructions_functions:
+            instructions += await instructions_runner.run(run_context)
+        return instructions
+
 
 async def _prepare_request_parameters(
     ctx: GraphRunContext[GraphAgentState, GraphAgentDeps[DepsT, NodeRunEndT]],