Pydantic AIPydantic AI 2.51 · Python 3.10+
Dashboard
0%
1
Curious builder0 XP earned · 300 to level 2
0 daysFinish a lesson to begin
Badge collection0 of 6 unlocked
29 small wins to finish your pathNext lesson →

Instructions: what the model is told

Instructions are the text that tells the model its job; they can be a fixed string, a function that runs at the start of every run, or extra text for one run.

Last updated: 28 Sep, 2026 · Pydantic AI 2.51

The model function in FunctionModel: write a stand-in model read the ticket. Here it reads info.instructions instead and answers with them, so you see the exact text a real model would be sent.

Answering with the instructions received

python
from pydantic_ai import Agent, ModelResponse, TextPart
from pydantic_ai.models.function import FunctionModel


def show_instructions(messages, info):
    return ModelResponse(parts=[TextPart(info.instructions or "(no instructions)")])


spy = FunctionModel(show_instructions)

Setting a fixed instruction string

Example
agent = Agent(spy, instructions="You answer support tickets for an online shop.")
print(agent.run_sync("hi").output)

Adding instructions that change each run

shop_status stands for something your app knows, such as a delivery problem. A function registered with @agent.instructions runs at the start of every run:

Example
@agent.instructions
def deliveries() -> str:
    if shop_status["delayed"]:
        return "Deliveries are running two days late. Say so when asked about a parcel."
    return ""


print(agent.run_sync("hi").output)
print("---")
shop_status["delayed"] = True
print(agent.run_sync("hi").output)

Why the second run differs

  • The function runs per run, so the second run sees the shop as it is at that moment.
  • Returning an empty string adds nothing, which is why the first run shows only the fixed text.
  • All the pieces are joined into one string, separated by blank lines, and sent to the model.

Adding instructions for one run

Example
agent = Agent(spy, instructions="You answer support tickets for an online shop.")
print(agent.run_sync("hi", instructions="Reply in Hindi.").output)

Text passed to run_sync is added for that run only, after the agent's own instructions.

instructions vs system_prompt

instructionssystem_prompt
Stored in the messagesNoYes
Sent when a chat continuesThe current agent's, freshlyThe stored one, again
Docs recommendYes, by defaultOnly to keep the old prompt

When to use each kind

  • A fixed string for the agent's standing job.
  • An @agent.instructions function for anything that changes between runs, such as live shop status.
  • Per-run text for a one-off tweak, such as a language for this reply.
Watch out. Instructions are not stored in the message list, so a continued conversation always sends the current agent's instructions, not the ones from the first run. Use system_prompt when you need the original text kept.
Try it yourself
  • Register a second @agent.instructions function and see where its text appears.
  • Return None from deliveries instead of an empty string.
  • Pass instructions=["Be short.", "Be kind."] to Agent.
PreviousFunctionModel: write a stand-in model

Every expert started right here.