Implementation:Openai Openai agents python Prompt Template Pattern

Knowledge Sources	Openai_Openai_agents_python
Domains	Prompt Engineering, Agent Configuration, Template Management
Last Updated	2026-02-11 00:00 GMT

Overview

Demonstrates using OpenAI platform-hosted prompt templates with agents, supporting both static dictionary-based prompts and dynamic async-function-based prompts that resolve at runtime.

Description

The Prompt Template pattern allows agents to use prompts that are managed on the OpenAI platform rather than being hardcoded in application code. This enables prompt versioning, A/B testing, and centralized prompt management. Prompts are referenced by their platform ID and version, with support for template variables that are substituted at invocation time.

The example shows two approaches. The static approach sets the agent's prompt parameter to a dictionary containing the prompt ID, version, and a variables mapping (e.g., {"id": prompt_id, "version": "1", "variables": {"poem_style": "limerick"}}). The dynamic approach sets prompt to an async function that receives a GenerateDynamicPromptData object and returns the same dictionary structure, allowing runtime logic to determine the prompt variables. In the example, the dynamic function reads the poem_style from a custom context object (DynamicContext) that randomly selects between "limerick", "haiku", and "ballad".

Both approaches integrate seamlessly with Runner.run(). The static approach is simpler and suitable when prompt variables are known at agent creation time, while the dynamic approach is ideal when variables depend on runtime state, user context, or external data sources. The prompt template must be pre-created on the OpenAI platform before use.

Usage

Use this pattern when you want to decouple prompt content from application code, enable non-developer prompt editing via the OpenAI platform, or dynamically select prompt parameters based on runtime context such as user preferences, A/B test cohorts, or session state.

Code Reference

Source Location

• Repository: Openai_Openai_agents_python
• File: examples/basic/prompt_template.py
• Lines: 1-79

Signature

# Static prompt
Agent(
    name="Assistant",
    prompt={
        "id": prompt_id,
        "version": "1",
        "variables": {
            "poem_style": "limerick",
        },
    },
)

# Dynamic prompt
Agent(
    name="Assistant",
    prompt=_get_dynamic_prompt,  # async function returning the dict
)

Import

from agents import Agent, GenerateDynamicPromptData, Runner

I/O Contract

Inputs

Name	Type	Required	Description
prompt	Callable	Yes	Either a dictionary with id, version, and variables keys, or an async function accepting GenerateDynamicPromptData and returning such a dictionary
prompt.id	str	Yes	The platform-hosted prompt template identifier
prompt.version	str	Yes	The version of the prompt template to use
prompt.variables	dict[str, str]	Yes	A mapping of template variable names to their values
context	Any	No	Custom context object passed to Runner.run(), accessible inside dynamic prompt functions via data.context.context

Outputs

Name	Type	Description
result.final_output	str	The agent's text response generated using the resolved prompt template

Usage Examples

Static Prompt Template

import asyncio
from agents import Agent, Runner

async def static_prompt(prompt_id: str):
    agent = Agent(
        name="Assistant",
        prompt={
            "id": prompt_id,
            "version": "1",
            "variables": {
                "poem_style": "limerick",
            },
        },
    )

    result = await Runner.run(agent, "Tell me about recursion in programming.")
    print(result.final_output)

asyncio.run(static_prompt("pmpt_your_prompt_id_here"))

Dynamic Prompt Template

import asyncio
import random
from agents import Agent, GenerateDynamicPromptData, Runner

class DynamicContext:
    def __init__(self, prompt_id: str):
        self.prompt_id = prompt_id
        self.poem_style = random.choice(["limerick", "haiku", "ballad"])

async def _get_dynamic_prompt(data: GenerateDynamicPromptData):
    ctx: DynamicContext = data.context.context
    return {
        "id": ctx.prompt_id,
        "version": "1",
        "variables": {
            "poem_style": ctx.poem_style,
        },
    }

async def dynamic_prompt(prompt_id: str):
    context = DynamicContext(prompt_id)
    agent = Agent(
        name="Assistant",
        prompt=_get_dynamic_prompt,
    )
    result = await Runner.run(agent, "Tell me about recursion in programming.", context=context)
    print(result.final_output)

asyncio.run(dynamic_prompt("pmpt_your_prompt_id_here"))

Related Pages

• Environment:Openai_Openai_agents_python_OpenAI_API_Credentials