Skip to content

Commit 37a899b

Browse files
author
baek54321
committed
Add instructions argument to run methods of agent class.
1 parent 9c31521 commit 37a899b

File tree

5 files changed

+73
-5
lines changed

5 files changed

+73
-5
lines changed

‎docs/agents.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -907,11 +907,14 @@ In general, we recommend using `instructions` instead of `system_prompt` unless
907907
Instructions, like system prompts, fall into two categories:
908908

909909
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__].
910-
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.
910+
2. **Dynamic instructions**: These rely on context that is only available at runtime. Dynamic instructions can be further divided into *temporary* dynamic instructions which are used only for a
911+
single run and *permanent* dynamic instructions, which are used for all runs.
912+
- **Dynamic temporary instructions*: Should be defined via the *instructions* argument to any of the `run` methods and will be effective only for the specific run for which they have been specified
913+
- **Dynamic permanent instructions*: 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.
911914

912915
Both static and dynamic instructions can be added to a single agent, and they are appended in the order they are defined at runtime.
913916

914-
Here's an example using both types of instructions:
917+
Here's an example using a static instruction as well as permanent dynamic instructions:
915918

916919
```python {title="instructions.py"}
917920
from datetime import date

‎pydantic_ai_slim/pydantic_ai/agent/__init__.py‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,7 @@ def __init__(
238238
output_type: The type of the output data, used to validate the data returned by the model,
239239
defaults to `str`.
240240
instructions: Instructions to use for this agent, you can also register instructions via a function with
241-
[`instructions`][pydantic_ai.Agent.instructions].
241+
[`instructions`][pydantic_ai.Agent.instructions] or pass additional, temporary, instructions when executing a run.
242242
system_prompt: Static system prompts to use for this agent, you can also register system
243243
prompts via a function with [`system_prompt`][pydantic_ai.Agent.system_prompt].
244244
deps_type: The type used for dependency injection, this parameter exists solely to allow you to fully
@@ -418,6 +418,7 @@ def iter(
418418
message_history: Sequence[_messages.ModelMessage] | None = None,
419419
deferred_tool_results: DeferredToolResults | None = None,
420420
model: models.Model | models.KnownModelName | str | None = None,
421+
instructions: Instructions[AgentDepsT] = None,
421422
deps: AgentDepsT = None,
422423
model_settings: ModelSettings | None = None,
423424
usage_limits: _usage.UsageLimits | None = None,
@@ -436,6 +437,7 @@ def iter(
436437
message_history: Sequence[_messages.ModelMessage] | None = None,
437438
deferred_tool_results: DeferredToolResults | None = None,
438439
model: models.Model | models.KnownModelName | str | None = None,
440+
instructions: Instructions[AgentDepsT] = None,
439441
deps: AgentDepsT = None,
440442
model_settings: ModelSettings | None = None,
441443
usage_limits: _usage.UsageLimits | None = None,
@@ -454,6 +456,7 @@ async def iter(
454456
message_history: Sequence[_messages.ModelMessage] | None = None,
455457
deferred_tool_results: DeferredToolResults | None = None,
456458
model: models.Model | models.KnownModelName | str | None = None,
459+
instructions: Instructions[AgentDepsT] = None,
457460
deps: AgentDepsT = None,
458461
model_settings: ModelSettings | None = None,
459462
usage_limits: _usage.UsageLimits | None = None,
@@ -527,6 +530,7 @@ async def main():
527530
message_history: History of the conversation so far.
528531
deferred_tool_results: Optional results for deferred tool calls in the message history.
529532
model: Optional model to use for this run, required if `model` was not set when creating the agent.
533+
instructions: Optional instructions to append to the instructions provided at the initialization of the agent and only to be used for this run.
530534
deps: Optional dependencies to use for this run.
531535
model_settings: Optional settings to use for this model's request.
532536
usage_limits: Optional limits on model request count or token usage.
@@ -580,7 +584,7 @@ async def main():
580584
model_settings = merge_model_settings(merged_settings, model_settings)
581585
usage_limits = usage_limits or _usage.UsageLimits()
582586

583-
instructions_literal, instructions_functions = self._get_instructions()
587+
instructions_literal, instructions_functions = self._get_instructions(additional_instructions=instructions)
584588

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

13311335
def _get_instructions(
13321336
self,
1337+
additional_instructions: Instructions[AgentDepsT] = None,
13331338
) -> tuple[str | None, list[_system_prompt.SystemPromptRunner[AgentDepsT]]]:
13341339
override_instructions = self._override_instructions.get()
1335-
instructions = override_instructions.value if override_instructions else self._instructions
1340+
if override_instructions:
1341+
instructions = override_instructions.value
1342+
else:
1343+
instructions = self._instructions.copy()
1344+
if additional_instructions is not None:
1345+
instructions.extend(self._normalize_instructions(additional_instructions))
13361346

13371347
literal_parts: list[str] = []
13381348
functions: list[_system_prompt.SystemPromptRunner[AgentDepsT]] = []

‎pydantic_ai_slim/pydantic_ai/agent/abstract.py‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,7 @@ async def run(
132132
message_history: Sequence[_messages.ModelMessage] | None = None,
133133
deferred_tool_results: DeferredToolResults | None = None,
134134
model: models.Model | models.KnownModelName | str | None = None,
135+
instructions: Instructions[AgentDepsT] = None,
135136
deps: AgentDepsT = None,
136137
model_settings: ModelSettings | None = None,
137138
usage_limits: _usage.UsageLimits | None = None,
@@ -151,6 +152,7 @@ async def run(
151152
message_history: Sequence[_messages.ModelMessage] | None = None,
152153
deferred_tool_results: DeferredToolResults | None = None,
153154
model: models.Model | models.KnownModelName | str | None = None,
155+
instructions: Instructions[AgentDepsT] = None,
154156
deps: AgentDepsT = None,
155157
model_settings: ModelSettings | None = None,
156158
usage_limits: _usage.UsageLimits | None = None,
@@ -169,6 +171,7 @@ async def run(
169171
message_history: Sequence[_messages.ModelMessage] | None = None,
170172
deferred_tool_results: DeferredToolResults | None = None,
171173
model: models.Model | models.KnownModelName | str | None = None,
174+
instructions: Instructions[AgentDepsT] = None,
172175
deps: AgentDepsT = None,
173176
model_settings: ModelSettings | None = None,
174177
usage_limits: _usage.UsageLimits | None = None,
@@ -202,6 +205,7 @@ async def main():
202205
message_history: History of the conversation so far.
203206
deferred_tool_results: Optional results for deferred tool calls in the message history.
204207
model: Optional model to use for this run, required if `model` was not set when creating the agent.
208+
instructions: Optional instructions to append to the instructions provided at the initialization of the agent and only to be used for this run.
205209
deps: Optional dependencies to use for this run.
206210
model_settings: Optional settings to use for this model's request.
207211
usage_limits: Optional limits on model request count or token usage.
@@ -225,6 +229,7 @@ async def main():
225229
message_history=message_history,
226230
deferred_tool_results=deferred_tool_results,
227231
model=model,
232+
instructions=instructions,
228233
deps=deps,
229234
model_settings=model_settings,
230235
usage_limits=usage_limits,
@@ -251,6 +256,7 @@ def run_sync(
251256
message_history: Sequence[_messages.ModelMessage] | None = None,
252257
deferred_tool_results: DeferredToolResults | None = None,
253258
model: models.Model | models.KnownModelName | str | None = None,
259+
instructions: Instructions[AgentDepsT] = None,
254260
deps: AgentDepsT = None,
255261
model_settings: ModelSettings | None = None,
256262
usage_limits: _usage.UsageLimits | None = None,
@@ -270,6 +276,7 @@ def run_sync(
270276
message_history: Sequence[_messages.ModelMessage] | None = None,
271277
deferred_tool_results: DeferredToolResults | None = None,
272278
model: models.Model | models.KnownModelName | str | None = None,
279+
instructions: Instructions[AgentDepsT] = None,
273280
deps: AgentDepsT = None,
274281
model_settings: ModelSettings | None = None,
275282
usage_limits: _usage.UsageLimits | None = None,
@@ -288,6 +295,7 @@ def run_sync(
288295
message_history: Sequence[_messages.ModelMessage] | None = None,
289296
deferred_tool_results: DeferredToolResults | None = None,
290297
model: models.Model | models.KnownModelName | str | None = None,
298+
instructions: Instructions[AgentDepsT] = None,
291299
deps: AgentDepsT = None,
292300
model_settings: ModelSettings | None = None,
293301
usage_limits: _usage.UsageLimits | None = None,
@@ -320,6 +328,7 @@ def run_sync(
320328
message_history: History of the conversation so far.
321329
deferred_tool_results: Optional results for deferred tool calls in the message history.
322330
model: Optional model to use for this run, required if `model` was not set when creating the agent.
331+
instructions: Optional instructions to append to the instructions provided at the initialization of the agent and only to be used for this run.
323332
deps: Optional dependencies to use for this run.
324333
model_settings: Optional settings to use for this model's request.
325334
usage_limits: Optional limits on model request count or token usage.
@@ -342,6 +351,7 @@ def run_sync(
342351
message_history=message_history,
343352
deferred_tool_results=deferred_tool_results,
344353
model=model,
354+
instructions=instructions,
345355
deps=deps,
346356
model_settings=model_settings,
347357
usage_limits=usage_limits,
@@ -362,6 +372,7 @@ def run_stream(
362372
message_history: Sequence[_messages.ModelMessage] | None = None,
363373
deferred_tool_results: DeferredToolResults | None = None,
364374
model: models.Model | models.KnownModelName | str | None = None,
375+
instructions: Instructions[AgentDepsT] = None,
365376
deps: AgentDepsT = None,
366377
model_settings: ModelSettings | None = None,
367378
usage_limits: _usage.UsageLimits | None = None,
@@ -381,6 +392,7 @@ def run_stream(
381392
message_history: Sequence[_messages.ModelMessage] | None = None,
382393
deferred_tool_results: DeferredToolResults | None = None,
383394
model: models.Model | models.KnownModelName | str | None = None,
395+
instructions: Instructions[AgentDepsT] = None,
384396
deps: AgentDepsT = None,
385397
model_settings: ModelSettings | None = None,
386398
usage_limits: _usage.UsageLimits | None = None,
@@ -400,6 +412,7 @@ async def run_stream( # noqa C901
400412
message_history: Sequence[_messages.ModelMessage] | None = None,
401413
deferred_tool_results: DeferredToolResults | None = None,
402414
model: models.Model | models.KnownModelName | str | None = None,
415+
instructions: Instructions[AgentDepsT] = None,
403416
deps: AgentDepsT = None,
404417
model_settings: ModelSettings | None = None,
405418
usage_limits: _usage.UsageLimits | None = None,
@@ -440,6 +453,7 @@ async def main():
440453
message_history: History of the conversation so far.
441454
deferred_tool_results: Optional results for deferred tool calls in the message history.
442455
model: Optional model to use for this run, required if `model` was not set when creating the agent.
456+
instructions: Optional instructions to append to the instructions provided at the initialization of the agent and only to be used for this run.
443457
deps: Optional dependencies to use for this run.
444458
model_settings: Optional settings to use for this model's request.
445459
usage_limits: Optional limits on model request count or token usage.
@@ -469,6 +483,7 @@ async def main():
469483
deferred_tool_results=deferred_tool_results,
470484
model=model,
471485
deps=deps,
486+
instructions=instructions,
472487
model_settings=model_settings,
473488
usage_limits=usage_limits,
474489
usage=usage,
@@ -590,6 +605,7 @@ def run_stream_events(
590605
message_history: Sequence[_messages.ModelMessage] | None = None,
591606
deferred_tool_results: DeferredToolResults | None = None,
592607
model: models.Model | models.KnownModelName | str | None = None,
608+
instructions: Instructions[AgentDepsT] = None,
593609
deps: AgentDepsT = None,
594610
model_settings: ModelSettings | None = None,
595611
usage_limits: _usage.UsageLimits | None = None,
@@ -608,6 +624,7 @@ def run_stream_events(
608624
message_history: Sequence[_messages.ModelMessage] | None = None,
609625
deferred_tool_results: DeferredToolResults | None = None,
610626
model: models.Model | models.KnownModelName | str | None = None,
627+
instructions: Instructions[AgentDepsT] = None,
611628
deps: AgentDepsT = None,
612629
model_settings: ModelSettings | None = None,
613630
usage_limits: _usage.UsageLimits | None = None,
@@ -625,6 +642,7 @@ def run_stream_events(
625642
message_history: Sequence[_messages.ModelMessage] | None = None,
626643
deferred_tool_results: DeferredToolResults | None = None,
627644
model: models.Model | models.KnownModelName | str | None = None,
645+
instructions: Instructions[AgentDepsT] = None,
628646
deps: AgentDepsT = None,
629647
model_settings: ModelSettings | None = None,
630648
usage_limits: _usage.UsageLimits | None = None,
@@ -674,6 +692,7 @@ async def main():
674692
message_history: History of the conversation so far.
675693
deferred_tool_results: Optional results for deferred tool calls in the message history.
676694
model: Optional model to use for this run, required if `model` was not set when creating the agent.
695+
instructions: Optional instructions to append to the instructions provided at the initialization of the agent and only to be used for this run.
677696
deps: Optional dependencies to use for this run.
678697
model_settings: Optional settings to use for this model's request.
679698
usage_limits: Optional limits on model request count or token usage.
@@ -698,6 +717,7 @@ async def main():
698717
message_history=message_history,
699718
deferred_tool_results=deferred_tool_results,
700719
model=model,
720+
instructions=instructions,
701721
deps=deps,
702722
model_settings=model_settings,
703723
usage_limits=usage_limits,
@@ -714,6 +734,7 @@ async def _run_stream_events(
714734
message_history: Sequence[_messages.ModelMessage] | None = None,
715735
deferred_tool_results: DeferredToolResults | None = None,
716736
model: models.Model | models.KnownModelName | str | None = None,
737+
instructions: Instructions[AgentDepsT] = None,
717738
deps: AgentDepsT = None,
718739
model_settings: ModelSettings | None = None,
719740
usage_limits: _usage.UsageLimits | None = None,
@@ -739,6 +760,7 @@ async def run_agent() -> AgentRunResult[Any]:
739760
message_history=message_history,
740761
deferred_tool_results=deferred_tool_results,
741762
model=model,
763+
instructions=instructions,
742764
deps=deps,
743765
model_settings=model_settings,
744766
usage_limits=usage_limits,
@@ -767,6 +789,7 @@ def iter(
767789
message_history: Sequence[_messages.ModelMessage] | None = None,
768790
deferred_tool_results: DeferredToolResults | None = None,
769791
model: models.Model | models.KnownModelName | str | None = None,
792+
instructions: Instructions[AgentDepsT] = None,
770793
deps: AgentDepsT = None,
771794
model_settings: ModelSettings | None = None,
772795
usage_limits: _usage.UsageLimits | None = None,
@@ -785,6 +808,7 @@ def iter(
785808
message_history: Sequence[_messages.ModelMessage] | None = None,
786809
deferred_tool_results: DeferredToolResults | None = None,
787810
model: models.Model | models.KnownModelName | str | None = None,
811+
instructions: Instructions[AgentDepsT] = None,
788812
deps: AgentDepsT = None,
789813
model_settings: ModelSettings | None = None,
790814
usage_limits: _usage.UsageLimits | None = None,
@@ -804,6 +828,7 @@ async def iter(
804828
message_history: Sequence[_messages.ModelMessage] | None = None,
805829
deferred_tool_results: DeferredToolResults | None = None,
806830
model: models.Model | models.KnownModelName | str | None = None,
831+
instructions: Instructions[AgentDepsT] = None,
807832
deps: AgentDepsT = None,
808833
model_settings: ModelSettings | None = None,
809834
usage_limits: _usage.UsageLimits | None = None,
@@ -877,6 +902,7 @@ async def main():
877902
message_history: History of the conversation so far.
878903
deferred_tool_results: Optional results for deferred tool calls in the message history.
879904
model: Optional model to use for this run, required if `model` was not set when creating the agent.
905+
instructions: Optional instructions to append to the instructions provided at the initialization of the agent and only to be used for this run.
880906
deps: Optional dependencies to use for this run.
881907
model_settings: Optional settings to use for this model's request.
882908
usage_limits: Optional limits on model request count or token usage.

0 commit comments

Comments
 (0)