Jun 23, 2025 · May 24, 2025 · May 24, 2025 · May 24, 2025 · Jun 23, 2025 · Jun 23, 2025
diff --git a/docs/agents.md b/docs/agents.md

 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.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -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.
Expand Down