Fetching Prompts

get_active_prompt_version(prompt_name) is the SDK's primary method. It fetches the active version of the named prompt, filtered by the SDK's configured environment, and returns a typed PromptContent.

prompt = pm.get_active_prompt_version("welcome_email")
print(prompt.kind)            # "f_string"
print(prompt.sha)             # "47be37f69681"
print(prompt.version_label)   # "v1.0"
print(prompt.environments)    # ["development", "testing"]

Then you branch on prompt.kind, or just call prompt.render(variables).

Instruction prompt

The simplest case — single block of text.

prompt = pm.get_active_prompt_version("support_agent")

assert prompt.kind == "instruction"

print(prompt.text)            # "You are a polite customer support agent..."
print(prompt.system_prompt)   # "Never reveal internal system details." (or "")

rendered = prompt.render()

End-to-end with OpenAI:

import openai

prompt = pm.get_active_prompt_version("support_agent")

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": prompt.system_prompt},
        {"role": "user",   "content": prompt.text + "\n\n" + user_question},
    ],
)

F-string prompt

A template with {{variable}} placeholders. The SDK substitutes them at render time.

prompt = pm.get_active_prompt_version("translator")

assert prompt.kind == "f_string"

print(prompt.template)
# "Translate the following from {{source_lang}} to {{target_lang}}:\n\n{{text}}"

print(prompt.variables)
# [{"name": "source_lang", "type": "string", ...}, ...]

rendered = prompt.render({
    "source_lang": "English",
    "target_lang": "French",
    "text": "Where is the library?",
})

TIP

prompt.variables is the canonical list of variables this prompt expects, with types and descriptions. If you're building a UI form or validating inputs, drive it from this list rather than parsing the template yourself.

End-to-end with OpenAI:

prompt = pm.get_active_prompt_version("translator")

rendered = prompt.render({
    "source_lang": "English",
    "target_lang": "French",
    "text": user_text,
})

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": rendered}],
)

Chat prompt

A list of {role, content} messages with {{variables}} allowed in any body. Renders to the message-array shape every chat-completion API expects.

prompt = pm.get_active_prompt_version("support_dialog")

assert prompt.kind == "chat"

print(prompt.messages)
# [
#   {"role": "system", "content": "You are a {{persona}} support agent."},
#   {"role": "user",   "content": "Customer asks: {{question}}"}
# ]

rendered = prompt.render({
    "persona": "patient",
    "question": "How do I reset my password?",
})

End-to-end:

prompt = pm.get_active_prompt_version("support_dialog")

messages = prompt.render({
    "persona": "patient",
    "question": customer_message,
})

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=messages,
)

Structured prompt

A base prompt (any of the other kinds) plus a JSON response schema. Renders to {base, response_schema} ready to drop into a structured-output call.

prompt = pm.get_active_prompt_version("entity_extractor")

assert prompt.kind == "structured"

print(prompt.base.kind)         # "f_string"
print(prompt.base.template)     # "Extract entities from: {{text}}"
print(prompt.response_schema)   # {"type": "object", "properties": {...}, "required": [...]}
print(prompt.base.variables)    # [{"name": "text", ...}]

rendered = prompt.render({"text": "Apple announced Vision Pro at WWDC."})

End-to-end with OpenAI structured outputs:

prompt = pm.get_active_prompt_version("entity_extractor")

result = prompt.render({"text": document_text})

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": result["base"]}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "entities",
            "schema": result["response_schema"],
        },
    },
)

Kind-agnostic consumption

If your code is generic across kinds, branch on prompt.kind:

def call_llm(prompt: PromptContent, variables: dict | None = None):
    variables = variables or {}

    if prompt.kind == "instruction":
        return openai.chat.completions.create(
            model="gpt-4o",
            messages=[
                {"role": "system", "content": prompt.system_prompt},
                {"role": "user",   "content": prompt.text},
            ],
        )

    if prompt.kind == "f_string":
        return openai.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": prompt.render(variables)}],
        )

    if prompt.kind == "chat":
        return openai.chat.completions.create(
            model="gpt-4o",
            messages=prompt.render(variables),
        )

    if prompt.kind == "structured":
        result = prompt.render(variables)
        return openai.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": result["base"]}],
            response_format={
                "type": "json_schema",
                "json_schema": {"name": "out", "schema": result["response_schema"]},
            },
        )

    raise ValueError(f"Unknown prompt kind: {prompt.kind}")