Support for Dynamic Instructions

[xflashxx]

Description

Hi everyone,

First off, thank you to all contributors for this fantastic library — your work is greatly appreciated!

I recently ran into a limitation when passing message history to an agent: the agent’s system prompts are overridden by any system prompts present in the message history. To avoid this, one can switch to using instructions instead of system prompts according to the docs, since system prompts/instructions in the message history do not override the agent's configured instructions. So far so good!

However, I couldn't find any equivalent to dynamic system prompts when using instructions. In my case, I need to extend the agent's instructions with runtime-specific information. Supporting dynamic instructions would enable this use case and bring feature parity with dynamic system prompts.

Thanks for considering this!

References

No response

[kauabh]

Hey @xflashxx I believe dynamic instruction are supported. Check below examples

Example 1

from pydantic_ai import Agent

user_is_logged_in = False
instructions = [
    "Reply with user Name John " if user_is_logged_in else "Reply with user Name Guest ",
]

agent = Agent(model=model,  name = "cool agent", instructions=instructions  )

result = agent.run_sync('hello world')

print(result.output)

Hello, Guest! How can I assist you today? 😊

Example 2

from pydantic_ai import Agent, RunContext

def agent_instruction(ctx: RunContext[str]) -> str:
    return f"Always use user name {ctx.deps} while responding"

agent = Agent(model=model, deps_type=str,   instructions=agent_instruction  )

result = agent.run_sync('hello world', deps='John')

print(result.output)

Hello, John! How are you doing today? 😊

[xflashxx]

Hey @kauabh , thanks for your reply!

You're right — this is currently possible. However, your second example comes with a trade-off: it requires introducing additional dependencies directly into the agent, which can quickly lead to boilerplate, especially when working with agents inside a graph/node context.

With native support for dynamic instructions, one could write a much more concise and readable node like this:

import dataclasses

from pydantic_ai import Agent
from pydantic_graph import BaseNode, GraphRunContext, End

agent = Agent(model="openai:gpt-4o", instructions="You are a helpful assistant.")

@dataclasses.dataclass
class Answer(BaseNode):
    username: str | None
    rag_document_contents: list[str] | None

    async def run(self, ctx: GraphRunContext[None]) -> End[str]:
        if self.username:
            @agent.instructions(dynamic=True)
            def add_username() -> str:
                return f"Always use user name {self.username} while responding."

        if self.rag_document_contents:
            @agent.instructions(dynamic=True)
            def add_rag_contents() -> str:
                return (
                    f"Consider the following information in your response: "
                    f"{self.rag_document_contents}"
                )

        result = await agent.run(user_prompt="hello world")
        return End(result.output)

Without dynamic instructions, though, we have to introduce a separate dependency type and instruction construction logic, like so:

import dataclasses

from pydantic_ai import Agent, RunContext
from pydantic_graph import BaseNode, GraphRunContext, End


@dataclasses.dataclass(slots=True, frozen=True)
class AgentDeps:
    user_name: str | None = None
    rag_document_contents: list[str] | None = None


def agent_instruction(ctx: RunContext[AgentDeps]) -> str:
    _prompt: str = "You are a helpful assistant."

    if ctx.deps.user_name is not None:
        _prompt += f" Always use user name {ctx.deps.user_name} while responding."

    if ctx.deps.rag_document_contents:
        _prompt += (
            f" Consider the following information in your response: "
            f"{'\n'.join(ctx.deps.rag_document_contents)}"
        )

    return _prompt


agent = Agent[AgentDeps, str](
    model="openai:gpt-4o", instructions=agent_instruction, deps_type=AgentDeps
)


@dataclasses.dataclass
class Answer(BaseNode):
    username: str | None
    rag_document_contents: list[str] | None

    async def run(self, ctx: GraphRunContext[None]) -> End[str]:
        agent_deps = AgentDeps(
            user_name=self.username,
            rag_document_contents=self.rag_document_contents,
        )

        result = await agent.run(user_prompt="hello world", deps=agent_deps)
        return End(result.output)

This works fine for a single agent, but as soon as dynamic instruction logic is needed across multiple nodes, the extra indirection and dependency boilerplate can quickly add up. Built-in support for dynamic instructions would really simplify this pattern 😊

(Although I have to admit that I really like the idea of constructing the prompt in a single place instead of having dynamic prompts all over the place 😅)

[kauabh]

Hmmm, I see your point. Personally, managing all dependencies in one place sounds cleaner to me, but your example does raise some important points.

[kauabh]

I believe you must have seen this example earlier from documentation (just sharing for the sake of completness ) https://ai.pydantic.dev/api/agent/#pydantic_ai.agent.Agent.instructions but yeah it still require defining deps

from pydantic_ai import Agent, RunContext

agent = Agent('test', deps_type=str)

@agent.instructions
def simple_instructions() -> str:
    return 'foobar'

@agent.instructions
async def async_instructions(ctx: RunContext[str]) -> str:
    return f'{ctx.deps} is the best'

[xflashxx]

Yes, I saw that, but I couldn’t find anything analogous to dynamic system prompts for instructions.

[HamzaFarhan]

Instructions are dynamic by nature. They don't need dynamic=True

[xflashxx]

Thank you @HamzaFarhan !

I can confirm that the above code works:

I believe you must have seen this example earlier from documentation (just sharing for the sake of completness ) https://ai.pydantic.dev/api/agent/#pydantic_ai.agent.Agent.instructions but yeah it still require defining deps

from pydantic_ai import Agent, RunContext

agent = Agent('test', deps_type=str)

@agent.instructions
def simple_instructions() -> str:
    return 'foobar'

@agent.instructions
async def async_instructions(ctx: RunContext[str]) -> str:
    return f'{ctx.deps} is the best'

That said, it might be worth expanding the instructions section in the documentation to match the depth of the system prompts section, especially that instructions are dynamic by nature (compared to system prompts) — could help prevent similar questions in the future 😊

[DouweM]

@Kludex Can you please have a look here as you implemented instructions?

[Kludex]

@xflashxx would you like to contribute with documentation?

[xflashxx]

@Kludex See #1819