Implementation:Openai Openai agents python Dynamic System Prompt Pattern
| Knowledge Sources | |
|---|---|
| Domains | Agent_Configuration, Prompt_Engineering, Design_Pattern |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Demonstrates the callable instructions pattern where a Python function is passed as instructions= to an Agent, receiving RunContextWrapper and Agent at runtime and returning a dynamically generated system prompt string.
Description
The dynamic_system_prompt.py example demonstrates one of the most powerful configuration patterns in the OpenAI Agents SDK: using a callable function as the agent's system prompt instead of a static string. By passing a function reference to the instructions= parameter of Agent, the SDK invokes that function at runtime with the current RunContextWrapper and Agent instance, enabling the system prompt to adapt based on the run context.
The example defines a CustomContext dataclass with a style field that can be "haiku", "pirate", or "robot". The custom_instructions function inspects this context at runtime and returns the appropriate system prompt string. The agent is created with Agent(name="Chat agent", instructions=custom_instructions), and at execution time, a random style is selected, passed as context to Runner.run(), and the function dynamically determines the agent's behavior.
This pattern is essential for building agents whose behavior needs to change based on user preferences, session state, or any runtime condition without needing to create separate agent instances for each variation.
Usage
Use this pattern when you need agent instructions that vary based on runtime context -- for example, user preferences, session metadata, A/B testing conditions, or dynamically loaded configuration. Instead of creating multiple agents with different static prompts, create one agent with a callable that derives instructions from the run context.
Code Reference
Source Location
- Repository: Openai_Openai_agents_python
- File: examples/basic/dynamic_system_prompt.py
- Lines: 1-71
Signature
def custom_instructions(
run_context: RunContextWrapper[CustomContext], agent: Agent[CustomContext]
) -> str:
...
agent = Agent(
name="Chat agent",
instructions=custom_instructions,
)
Import
from agents import Agent, RunContextWrapper, Runner
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| run_context | RunContextWrapper[CustomContext] | Yes | Wrapper providing access to the custom context at runtime |
| agent | Agent[CustomContext] | Yes | The agent instance invoking the instructions function |
| context.style | Literal["haiku", "pirate", "robot"] | Yes | Determines which system prompt variant to return |
Outputs
| Name | Type | Description |
|---|---|---|
| return value | str | The dynamically generated system prompt string |
| result.final_output | str | The agent's response text, influenced by the dynamic prompt |
Usage Examples
Define a Custom Context and Dynamic Instructions
from dataclasses import dataclass
from typing import Literal
from agents import Agent, RunContextWrapper, Runner
@dataclass
class CustomContext:
style: Literal["haiku", "pirate", "robot"]
def custom_instructions(
run_context: RunContextWrapper[CustomContext], agent: Agent[CustomContext]
) -> str:
context = run_context.context
if context.style == "haiku":
return "Only respond in haikus."
elif context.style == "pirate":
return "Respond as a pirate."
else:
return "Respond as a robot and say 'beep boop' a lot."
agent = Agent(
name="Chat agent",
instructions=custom_instructions,
)
Run the Agent with Dynamic Context
import asyncio
import random
async def main():
context = CustomContext(style=random.choice(["haiku", "pirate", "robot"]))
result = await Runner.run(agent, "Tell me a joke.", context=context)
print(result.final_output)
asyncio.run(main())