Principle:Openai Openai agents python Prompt Templates
| Knowledge Sources | |
|---|---|
| Domains | Agent_Configuration, Prompt_Engineering |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Mechanism for using externally-hosted prompt templates with variable substitution as the system prompt source for an agent.
Description
Prompt Templates allow agents to use prompts stored on the OpenAI platform rather than inline strings. A prompt template is identified by an ID and version, and may contain variable placeholders (e.g., `Template:Poem style`) that are resolved at runtime. This separates prompt authoring from code, enabling prompt iteration without code changes.
The SDK supports two modes of prompt template usage: static prompts (a dict with `id`, `version`, and `variables` passed directly to the `prompt=` parameter) and dynamic prompts (an async function that receives `GenerateDynamicPromptData` and returns the same dict structure, enabling runtime variable resolution based on context).
When a prompt template is specified, it replaces the `instructions=` parameter entirely. The platform resolves the template server-side, substituting variables and returning the final system prompt text. This approach enables A/B testing of prompts, centralized prompt management, and context-dependent prompt selection.
Usage
Use this principle when you want to manage prompts externally on the OpenAI platform rather than hardcoding them in source code. Static prompts are appropriate when variables are known at agent construction time. Dynamic prompts are appropriate when variables depend on runtime context (e.g., user preferences, session state).
Theoretical Basis
Prompt Templates implement the Template Method pattern adapted for LLM system prompts:
Pseudo-code Logic:
# Abstract template resolution
if agent.prompt is callable:
prompt_spec = await agent.prompt(GenerateDynamicPromptData(context=run_context))
else:
prompt_spec = agent.prompt # static dict
# Server-side resolution
system_prompt = platform.resolve_template(
id=prompt_spec["id"],
version=prompt_spec["version"],
variables=prompt_spec["variables"]
)
The key design decisions are:
- Static vs dynamic: Two modes cover both fixed and context-dependent prompts.
- Server-side resolution: Variable substitution happens on the platform, not in user code.
- Versioning: Explicit version field enables reproducible behavior.