Improve Dynamic Instructions Documentation (#1819)

Co-authored-by: Marcelo Trylesinski <marcelotryle@gmail.com>

Author: xflashxx

docs/agents.md

@@ -682,49 +682,53 @@ You should use:
 
 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
+Instructions, like system prompts, fall into two categories:
 
-agent = Agent(
-    'openai:gpt-4o',
-    instructions='You are a helpful assistant that can answer questions and help with tasks.',  # (1)!
-)
+1. **Static instructions**: These are known when writing the code and can be defined via the `instructions` parameter of the [`Agent` constructor][pydantic_ai.Agent.__init__].
+2. **Dynamic instructions**: These rely on context that is only available at runtime and should be defined using functions decorated with [`@agent.instructions`][pydantic_ai.Agent.instructions]. Unlike dynamic system prompts, which may be reused when `message_history` is present, dynamic instructions are always reevaluated.
 
-result = agent.run_sync('What is the capital of France?')
-print(result.output)
-#> Paris
-```
+Both static and dynamic instructions can be added to a single agent, and they are appended in the order they are defined at runtime.
 
-1. This will be the only instructions for this agent.
+Here's an example using both types of instructions:
 
-_(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"}
+```python {title="instructions.py"}
 from datetime import date
 
 from pydantic_ai import Agent, RunContext
 
-agent = Agent('openai:gpt-4o', deps_type=str)
+agent = Agent(
+    'openai:gpt-4o',
+    deps_type=str,  # (1)!
+    instructions="Use the customer's name while replying to them.",  # (2)!
+)
 
 
-@agent.instructions
+@agent.instructions  # (3)!
 def add_the_users_name(ctx: RunContext[str]) -> str:
     return f"The user's name is {ctx.deps}."
 
 
 @agent.instructions
-def add_the_date() -> str:
+def add_the_date() -> str:  # (4)!
     return f'The date is {date.today()}.'
 
+
 result = agent.run_sync('What is the date?', deps='Frank')
 print(result.output)
 #> Hello Frank, the date today is 2032-01-02.
 ```
 
+1. The agent expects a string dependency.
+2. Static instructions defined at agent creation time.
+3. Dynamic instructions defined via a decorator with [`RunContext`][pydantic_ai.tools.RunContext],
+   this is called just after `run_sync`, not when the agent is created, so can benefit from runtime
+   information like the dependencies used on that run.
+4. Another dynamic instruction, instructions don't have to have the `RunContext` parameter.
+
+_(This example is complete, it can be run "as is")_
+
+Note that returning an empty string will result in no instruction message added.
+
 ## 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.