Encourage the usage of instructions in place of system_prompt by replacing existing examples and tests

docs/api/models/test.md

@@ -8,7 +8,7 @@ Here's a minimal example:
 from pydantic_ai import Agent
 from pydantic_ai.models.test import TestModel
 
-my_agent = Agent('openai:gpt-5', system_prompt='...')
+my_agent = Agent('openai:gpt-5', instructions='...')
 
 
 async def test_my_agent():

docs/common-tools.md

@@ -27,7 +27,7 @@ from pydantic_ai.common_tools.duckduckgo import duckduckgo_search_tool
 agent = Agent(
     'openai:o3-mini',
     tools=[duckduckgo_search_tool()],
-    system_prompt='Search DuckDuckGo for the given query and return the results.',
+    instructions='Search DuckDuckGo for the given query and return the results.',
 )
 
 result = agent.run_sync(
@@ -115,7 +115,7 @@ assert api_key is not None
 agent = Agent(
     'openai:o3-mini',
     tools=[tavily_search_tool(api_key)],
-    system_prompt='Search Tavily for the given query and return the results.',
+    instructions='Search Tavily for the given query and return the results.',
 )
 
 result = agent.run_sync('Tell me the top news in the GenAI world, give me links.')

docs/evals/evaluators/llm-judge.md

@@ -302,7 +302,7 @@ class Recipe(BaseModel):
 recipe_agent = Agent(
     'openai:gpt-5-mini',
     output_type=Recipe,
-    system_prompt=(
+    instructions=(
         'Generate a recipe to cook the dish that meets the dietary restrictions.'
     ),
 )

docs/evals/how-to/metrics-attributes.md

@@ -525,9 +525,9 @@ from pydantic_evals import Case, Dataset
 # Module constants as single source of truth
 MODEL_NAME = 'openai:gpt-5-mini'
 TEMPERATURE = 0.7
-SYSTEM_PROMPT = 'You are a helpful assistant.'
+INSTRUCTIONS = 'You are a helpful assistant.'
 
-agent = Agent(MODEL_NAME, model_settings={'temperature': TEMPERATURE}, system_prompt=SYSTEM_PROMPT)
+agent = Agent(MODEL_NAME, model_settings={'temperature': TEMPERATURE}, instructions=INSTRUCTIONS)
 
 
 async def task(inputs: str) -> str:
@@ -544,7 +544,7 @@ async def main():
         metadata={
             'model': MODEL_NAME,
             'temperature': TEMPERATURE,
-            'system_prompt': SYSTEM_PROMPT,
+            'instructions': INSTRUCTIONS,
         },
     )
 ```

docs/graph.md

@@ -385,7 +385,7 @@ class State:
 email_writer_agent = Agent(
     'google-gla:gemini-2.5-pro',
     output_type=Email,
-    system_prompt='Write a welcome email to our tech blog.',
+    instructions='Write a welcome email to our tech blog.',
 )
 
 
@@ -425,7 +425,7 @@ class EmailOk(BaseModel):
 feedback_agent = Agent[None, EmailRequiresWrite | EmailOk](
     'openai:gpt-5',
     output_type=EmailRequiresWrite | EmailOk,  # type: ignore
-    system_prompt=(
+    instructions=(
         'Review the email and provide feedback, email must reference the users specific interests.'
     ),
 )
@@ -708,7 +708,7 @@ class EvaluationResult(BaseModel, use_attribute_docstrings=True):
 evaluate_agent = Agent(
     'openai:gpt-5',
     output_type=EvaluationResult,
-    system_prompt='Given a question and answer, evaluate if the answer is correct.',
+    instructions='Given a question and answer, evaluate if the answer is correct.',
 )
 
 
@@ -951,7 +951,7 @@ class EvaluationResult(BaseModel, use_attribute_docstrings=True):
 evaluate_agent = Agent(
     'openai:gpt-5',
     output_type=EvaluationResult,
-    system_prompt='Given a question and answer, evaluate if the answer is correct.',
+    instructions='Given a question and answer, evaluate if the answer is correct.',
 )
 
 

docs/index.md

@@ -204,7 +204,7 @@ support_agent = Agent(
     'openai:gpt-5',
     deps_type=SupportDependencies,
     output_type=SupportOutput,
-    system_prompt=(
+    instructions=(
         'You are a support agent in our bank, give the '
         'customer support and judge the risk level of their query.'
     ),

docs/mcp/server.md

@@ -13,7 +13,7 @@ from pydantic_ai import Agent
 
 server = FastMCP('Pydantic AI Server')
 server_agent = Agent(
-    'anthropic:claude-haiku-4-5', system_prompt='always reply in rhyme'
+    'anthropic:claude-haiku-4-5', instructions='always reply in rhyme'
 )
 
 
@@ -77,7 +77,7 @@ from pydantic_ai import Agent
 from pydantic_ai.models.mcp_sampling import MCPSamplingModel
 
 server = FastMCP('Pydantic AI Server with sampling')
-server_agent = Agent(system_prompt='always reply in rhyme')
+server_agent = Agent(instructions='always reply in rhyme')
 
 
 @server.tool()

docs/message-history.md

@@ -30,7 +30,7 @@ Example of accessing methods on a [`RunResult`][pydantic_ai.agent.AgentRunResult
 ```python {title="run_result_messages.py" hl_lines="10"}
 from pydantic_ai import Agent
 
-agent = Agent('openai:gpt-5', system_prompt='Be a helpful assistant.')
+agent = Agent('openai:gpt-5', instructions='Be a helpful assistant.')
 
 result = agent.run_sync('Tell me a joke.')
 print(result.output)
@@ -42,15 +42,12 @@ print(result.all_messages())
 [
     ModelRequest(
         parts=[
-            SystemPromptPart(
-                content='Be a helpful assistant.',
-                timestamp=datetime.datetime(...),
-            ),
             UserPromptPart(
                 content='Tell me a joke.',
                 timestamp=datetime.datetime(...),
-            ),
+            )
         ],
+        instructions='Be a helpful assistant.',
         run_id='...',
     ),
     ModelResponse(
@@ -59,7 +56,7 @@ print(result.all_messages())
                 content='Did you hear about the toothpaste scandal? They called it Colgate.'
             )
         ],
-        usage=RequestUsage(input_tokens=60, output_tokens=12),
+        usage=RequestUsage(input_tokens=55, output_tokens=12),
         model_name='gpt-5',
         timestamp=datetime.datetime(...),
         run_id='...',
@@ -75,7 +72,7 @@ Example of accessing methods on a [`StreamedRunResult`][pydantic_ai.result.Strea
 ```python {title="streamed_run_result_messages.py" hl_lines="9 40"}
 from pydantic_ai import Agent
 
-agent = Agent('openai:gpt-5', system_prompt='Be a helpful assistant.')
+agent = Agent('openai:gpt-5', instructions='Be a helpful assistant.')
 
 
 async def main():
@@ -86,15 +83,12 @@ async def main():
         [
             ModelRequest(
                 parts=[
-                    SystemPromptPart(
-                        content='Be a helpful assistant.',
-                        timestamp=datetime.datetime(...),
-                    ),
                     UserPromptPart(
                         content='Tell me a joke.',
                         timestamp=datetime.datetime(...),
-                    ),
+                    )
                 ],
+                instructions='Be a helpful assistant.',
                 run_id='...',
             )
         ]
@@ -113,15 +107,12 @@ async def main():
         [
             ModelRequest(
                 parts=[
-                    SystemPromptPart(
-                        content='Be a helpful assistant.',
-                        timestamp=datetime.datetime(...),
-                    ),
                     UserPromptPart(
                         content='Tell me a joke.',
                         timestamp=datetime.datetime(...),
-                    ),
+                    )
                 ],
+                instructions='Be a helpful assistant.',
                 run_id='...',
             ),
             ModelResponse(
@@ -154,7 +145,7 @@ If `message_history` is set and not empty, a new system prompt is not generated
 ```python {title="Reusing messages in a conversation" hl_lines="9 13"}
 from pydantic_ai import Agent
 
-agent = Agent('openai:gpt-5', system_prompt='Be a helpful assistant.')
+agent = Agent('openai:gpt-5', instructions='Be a helpful assistant.')
 
 result1 = agent.run_sync('Tell me a joke.')
 print(result1.output)
@@ -169,15 +160,12 @@ print(result2.all_messages())
 [
     ModelRequest(
         parts=[
-            SystemPromptPart(
-                content='Be a helpful assistant.',
-                timestamp=datetime.datetime(...),
-            ),
             UserPromptPart(
                 content='Tell me a joke.',
                 timestamp=datetime.datetime(...),
-            ),
+            )
         ],
+        instructions='Be a helpful assistant.',
         run_id='...',
     ),
     ModelResponse(
@@ -186,7 +174,7 @@ print(result2.all_messages())
                 content='Did you hear about the toothpaste scandal? They called it Colgate.'
             )
         ],
-        usage=RequestUsage(input_tokens=60, output_tokens=12),
+        usage=RequestUsage(input_tokens=55, output_tokens=12),
         model_name='gpt-5',
         timestamp=datetime.datetime(...),
         run_id='...',
@@ -198,6 +186,7 @@ print(result2.all_messages())
                 timestamp=datetime.datetime(...),
             )
         ],
+        instructions='Be a helpful assistant.',
         run_id='...',
     ),
     ModelResponse(
@@ -206,7 +195,7 @@ print(result2.all_messages())
                 content='This is an excellent joke invented by Samuel Colvin, it needs no explanation.'
             )
         ],
-        usage=RequestUsage(input_tokens=61, output_tokens=26),
+        usage=RequestUsage(input_tokens=56, output_tokens=26),
         model_name='gpt-5',
         timestamp=datetime.datetime(...),
         run_id='...',
@@ -235,7 +224,7 @@ from pydantic_ai import (
     ModelMessagesTypeAdapter,  # (1)!
 )
 
-agent = Agent('openai:gpt-5', system_prompt='Be a helpful assistant.')
+agent = Agent('openai:gpt-5', instructions='Be a helpful assistant.')
 
 result1 = agent.run_sync('Tell me a joke.')
 history_step_1 = result1.all_messages()
@@ -275,7 +264,7 @@ In the example below, we reuse the message from the first agent run, which uses
 ```python {title="Reusing messages with a different model" hl_lines="17"}
 from pydantic_ai import Agent
 
-agent = Agent('openai:gpt-5', system_prompt='Be a helpful assistant.')
+agent = Agent('openai:gpt-5', instructions='Be a helpful assistant.')
 
 result1 = agent.run_sync('Tell me a joke.')
 print(result1.output)
@@ -294,15 +283,12 @@ print(result2.all_messages())
 [
     ModelRequest(
         parts=[
-            SystemPromptPart(
-                content='Be a helpful assistant.',
-                timestamp=datetime.datetime(...),
-            ),
             UserPromptPart(
                 content='Tell me a joke.',
                 timestamp=datetime.datetime(...),
-            ),
+            )
         ],
+        instructions='Be a helpful assistant.',
         run_id='...',
     ),
     ModelResponse(
@@ -311,7 +297,7 @@ print(result2.all_messages())
                 content='Did you hear about the toothpaste scandal? They called it Colgate.'
             )
         ],
-        usage=RequestUsage(input_tokens=60, output_tokens=12),
+        usage=RequestUsage(input_tokens=55, output_tokens=12),
         model_name='gpt-5',
         timestamp=datetime.datetime(...),
         run_id='...',
@@ -323,6 +309,7 @@ print(result2.all_messages())
                 timestamp=datetime.datetime(...),
             )
         ],
+        instructions='Be a helpful assistant.',
         run_id='...',
     ),
     ModelResponse(
@@ -331,7 +318,7 @@ print(result2.all_messages())
                 content='This is an excellent joke invented by Samuel Colvin, it needs no explanation.'
             )
         ],
-        usage=RequestUsage(input_tokens=61, output_tokens=26),
+        usage=RequestUsage(input_tokens=56, output_tokens=26),
         model_name='gemini-2.5-pro',
         timestamp=datetime.datetime(...),
         run_id='...',

docs/models/anthropic.md

@@ -100,7 +100,7 @@ from pydantic_ai.models.anthropic import AnthropicModelSettings
 
 agent = Agent(
     'anthropic:claude-sonnet-4-5',
-    system_prompt='You are a helpful assistant.',
+    instructions='You are a helpful assistant.',
     model_settings=AnthropicModelSettings(
         anthropic_cache_messages=True,  # Automatically caches the last message
     ),
@@ -125,7 +125,7 @@ from pydantic_ai.models.anthropic import AnthropicModelSettings
 
 agent = Agent(
     'anthropic:claude-sonnet-4-5',
-    system_prompt='Detailed instructions...',
+    instructions='Detailed instructions...',
     model_settings=AnthropicModelSettings(
         anthropic_cache_instructions=True,      # Cache system instructions
         anthropic_cache_tool_definitions='1h',  # Cache tool definitions with 1h TTL
@@ -152,7 +152,7 @@ from pydantic_ai import Agent, CachePoint
 
 agent = Agent(
     'anthropic:claude-sonnet-4-5',
-    system_prompt='Instructions...',
+    instructions='Instructions...',
 )
 
 # Manually control cache points for specific content blocks
@@ -174,7 +174,7 @@ from pydantic_ai.models.anthropic import AnthropicModelSettings
 
 agent = Agent(
     'anthropic:claude-sonnet-4-5',
-    system_prompt='Instructions...',
+    instructions='Instructions...',
     model_settings=AnthropicModelSettings(
         anthropic_cache_instructions=True  # Default 5m TTL
     ),
@@ -210,7 +210,7 @@ from pydantic_ai.models.anthropic import AnthropicModelSettings
 
 agent = Agent(
     'anthropic:claude-sonnet-4-5',
-    system_prompt='Detailed instructions...',
+    instructions='Detailed instructions...',
     model_settings=AnthropicModelSettings(
         anthropic_cache_instructions=True,      # 1 cache point
         anthropic_cache_tool_definitions=True,  # 1 cache point
@@ -247,7 +247,7 @@ from pydantic_ai.models.anthropic import AnthropicModelSettings
 
 agent = Agent(
     'anthropic:claude-sonnet-4-5',
-    system_prompt='Instructions...',
+    instructions='Instructions...',
     model_settings=AnthropicModelSettings(
         anthropic_cache_instructions=True,      # 1 cache point
         anthropic_cache_tool_definitions=True,  # 1 cache point