Skip to content

Let additional instructions be provided at agent.run time. #3309

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DouweM merged 5 commits into from
Nov 4, 2025
Merged

Let additional instructions be provided at agent.run time. #3309

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d4ac8c7
Add instructions argument to run methods of agent class.
Nov 2, 2025
5d5a9aa
Extend DBOS, Prefect and Temporal agent. Update docs after review.
Nov 4, 2025
199a638
Merge branch 'main' into feature/temporary_instructions
DouweM Nov 4, 2025
640a773
Update docs/agents.md
DouweM Nov 4, 2025
ea582de
Merge branch 'main' into feature/temporary_instructions
DouweM Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions docs/agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -904,14 +904,15 @@ You should use:

In general, we recommend using `instructions` instead of `system_prompt` unless you have a specific reason to use `system_prompt`.

Instructions, like system prompts, fall into two categories:
Instructions, like system prompts, can be specified at different times:

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.
3. **Runtime instructions*:: These can be used to pass additional instructions to the agent at runtime and are valid for that specific run.

Both static and dynamic instructions can be added to a single agent, and they are appended in the order they are defined at runtime.
All three types of instructions can be added to a single agent, and they are appended in the order they are defined at runtime.

Here's an example using both types of instructions:
Here's an example using a static instruction as well as dynamic instructions:

```python {title="instructions.py"}
from datetime import date
Expand Down
16 changes: 13 additions & 3 deletions pydantic_ai_slim/pydantic_ai/agent/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,7 +238,7 @@ def __init__(
output_type: The type of the output data, used to validate the data returned by the model,
defaults to `str`.
instructions: Instructions to use for this agent, you can also register instructions via a function with
[`instructions`][pydantic_ai.Agent.instructions].
[`instructions`][pydantic_ai.Agent.instructions] or pass additional, temporary, instructions when executing a run.
system_prompt: Static system prompts to use for this agent, you can also register system
prompts via a function with [`system_prompt`][pydantic_ai.Agent.system_prompt].
deps_type: The type used for dependency injection, this parameter exists solely to allow you to fully
Expand Down Expand Up @@ -418,6 +418,7 @@ def iter(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -436,6 +437,7 @@ def iter(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -454,6 +456,7 @@ async def iter(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand Down Expand Up @@ -527,6 +530,7 @@ async def main():
message_history: History of the conversation so far.
deferred_tool_results: Optional results for deferred tool calls in the message history.
model: Optional model to use for this run, required if `model` was not set when creating the agent.
instructions: Optional additional instructions to use for this run.
deps: Optional dependencies to use for this run.
model_settings: Optional settings to use for this model's request.
usage_limits: Optional limits on model request count or token usage.
Expand Down Expand Up @@ -580,7 +584,7 @@ async def main():
model_settings = merge_model_settings(merged_settings, model_settings)
usage_limits = usage_limits or _usage.UsageLimits()

instructions_literal, instructions_functions = self._get_instructions()
instructions_literal, instructions_functions = self._get_instructions(additional_instructions=instructions)

async def get_instructions(run_context: RunContext[AgentDepsT]) -> str | None:
parts = [
Expand Down Expand Up @@ -1330,9 +1334,15 @@ def _normalize_instructions(

def _get_instructions(
self,
additional_instructions: Instructions[AgentDepsT] = None,
) -> tuple[str | None, list[_system_prompt.SystemPromptRunner[AgentDepsT]]]:
override_instructions = self._override_instructions.get()
instructions = override_instructions.value if override_instructions else self._instructions
if override_instructions:
instructions = override_instructions.value
else:
instructions = self._instructions.copy()
if additional_instructions is not None:
instructions.extend(self._normalize_instructions(additional_instructions))

literal_parts: list[str] = []
functions: list[_system_prompt.SystemPromptRunner[AgentDepsT]] = []
Expand Down
26 changes: 26 additions & 0 deletions pydantic_ai_slim/pydantic_ai/agent/abstract.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,7 @@ async def run(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -150,6 +151,7 @@ async def run(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -168,6 +170,7 @@ async def run(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand Down Expand Up @@ -201,6 +204,7 @@ async def main():
message_history: History of the conversation so far.
deferred_tool_results: Optional results for deferred tool calls in the message history.
model: Optional model to use for this run, required if `model` was not set when creating the agent.
instructions: Optional additional instructions to use for this run.
deps: Optional dependencies to use for this run.
model_settings: Optional settings to use for this model's request.
usage_limits: Optional limits on model request count or token usage.
Expand All @@ -224,6 +228,7 @@ async def main():
message_history=message_history,
deferred_tool_results=deferred_tool_results,
model=model,
instructions=instructions,
deps=deps,
model_settings=model_settings,
usage_limits=usage_limits,
Expand All @@ -250,6 +255,7 @@ def run_sync(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -269,6 +275,7 @@ def run_sync(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -287,6 +294,7 @@ def run_sync(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand Down Expand Up @@ -319,6 +327,7 @@ def run_sync(
message_history: History of the conversation so far.
deferred_tool_results: Optional results for deferred tool calls in the message history.
model: Optional model to use for this run, required if `model` was not set when creating the agent.
instructions: Optional additional instructions to use for this run.
deps: Optional dependencies to use for this run.
model_settings: Optional settings to use for this model's request.
usage_limits: Optional limits on model request count or token usage.
Expand All @@ -341,6 +350,7 @@ def run_sync(
message_history=message_history,
deferred_tool_results=deferred_tool_results,
model=model,
instructions=instructions,
deps=deps,
model_settings=model_settings,
usage_limits=usage_limits,
Expand All @@ -361,6 +371,7 @@ def run_stream(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -380,6 +391,7 @@ def run_stream(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -399,6 +411,7 @@ async def run_stream( # noqa C901
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand Down Expand Up @@ -439,6 +452,7 @@ async def main():
message_history: History of the conversation so far.
deferred_tool_results: Optional results for deferred tool calls in the message history.
model: Optional model to use for this run, required if `model` was not set when creating the agent.
instructions: Optional additional instructions to use for this run.
deps: Optional dependencies to use for this run.
model_settings: Optional settings to use for this model's request.
usage_limits: Optional limits on model request count or token usage.
Expand Down Expand Up @@ -468,6 +482,7 @@ async def main():
deferred_tool_results=deferred_tool_results,
model=model,
deps=deps,
instructions=instructions,
model_settings=model_settings,
usage_limits=usage_limits,
usage=usage,
Expand Down Expand Up @@ -716,6 +731,7 @@ def run_stream_events(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -734,6 +750,7 @@ def run_stream_events(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -751,6 +768,7 @@ def run_stream_events(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand Down Expand Up @@ -800,6 +818,7 @@ async def main():
message_history: History of the conversation so far.
deferred_tool_results: Optional results for deferred tool calls in the message history.
model: Optional model to use for this run, required if `model` was not set when creating the agent.
instructions: Optional additional instructions to use for this run.
deps: Optional dependencies to use for this run.
model_settings: Optional settings to use for this model's request.
usage_limits: Optional limits on model request count or token usage.
Expand All @@ -824,6 +843,7 @@ async def main():
message_history=message_history,
deferred_tool_results=deferred_tool_results,
model=model,
instructions=instructions,
deps=deps,
model_settings=model_settings,
usage_limits=usage_limits,
Expand All @@ -840,6 +860,7 @@ async def _run_stream_events(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -865,6 +886,7 @@ async def run_agent() -> AgentRunResult[Any]:
message_history=message_history,
deferred_tool_results=deferred_tool_results,
model=model,
instructions=instructions,
deps=deps,
model_settings=model_settings,
usage_limits=usage_limits,
Expand Down Expand Up @@ -893,6 +915,7 @@ def iter(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -911,6 +934,7 @@ def iter(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -930,6 +954,7 @@ async def iter(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand Down Expand Up @@ -1003,6 +1028,7 @@ async def main():
message_history: History of the conversation so far.
deferred_tool_results: Optional results for deferred tool calls in the message history.
model: Optional model to use for this run, required if `model` was not set when creating the agent.
instructions: Optional additional instructions to use for this run.
deps: Optional dependencies to use for this run.
model_settings: Optional settings to use for this model's request.
usage_limits: Optional limits on model request count or token usage.
Expand Down
5 changes: 5 additions & 0 deletions pydantic_ai_slim/pydantic_ai/agent/wrapper.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@ def iter(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -94,6 +95,7 @@ def iter(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand All @@ -112,6 +114,7 @@ async def iter(
message_history: Sequence[_messages.ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: models.Model | models.KnownModelName | str | None = None,
instructions: Instructions[AgentDepsT] = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: _usage.UsageLimits | None = None,
Expand Down Expand Up @@ -185,6 +188,7 @@ async def main():
message_history: History of the conversation so far.
deferred_tool_results: Optional results for deferred tool calls in the message history.
model: Optional model to use for this run, required if `model` was not set when creating the agent.
instructions: Optional additional instructions to use for this run.
deps: Optional dependencies to use for this run.
model_settings: Optional settings to use for this model's request.
usage_limits: Optional limits on model request count or token usage.
Expand All @@ -202,6 +206,7 @@ async def main():
message_history=message_history,
deferred_tool_results=deferred_tool_results,
model=model,
instructions=instructions,
deps=deps,
model_settings=model_settings,
usage_limits=usage_limits,
Expand Down
Loading