get_prompt()

Fetch a prompt template from the Coalex Prompt Vault. Prompt Vault provides versioned, environment-aware prompt management -- serve different prompt versions to production, staging, or canary traffic without redeploying your agent.

Python SDK only

get_prompt() is currently available in the Python SDK only. TypeScript support is planned.

---

Signature

def get_prompt(
    *,
    agent: str,
    name: str,
    version: str | int = "production",
) -> PromptVersion

---

Parameters

Parameter	Type	Default	Description
agent	str	required	The agent identifier that owns the prompt.
name	str	required	The prompt template name.
version	str \| int	"production"	Which version to fetch. Accepts: "production", "staging", "draft", "latest", or an integer version number.

All parameters are keyword-only (enforced by *).

Requires register() first

get_prompt() uses the endpoint and API key configured by register(). Calling it before register() raises RuntimeError.

---

Returns

PromptVersion

@dataclass(frozen=True)
class PromptVersion:
    id: str
    agent_id: str
    name: str
    prompt_type: str
    version: int
    content: str
    status: str          # "production" | "staging" | "draft"
    metadata: dict | None

Field	Type	Description
id	str	Unique prompt version identifier.
agent_id	str	The agent that owns the prompt.
name	str	The prompt template name.
prompt_type	str	The type of prompt (e.g., "system", "user").
version	int	The version number.
content	str	The prompt template text. Use this as your system or user message.
status	str	The version's status: "production", "staging", or "draft".
metadata	dict \| None	Optional metadata attached to this prompt version.

---

Version Resolution

version parameter	Behavior
"production" (default)	Returns the version currently marked as production.
"staging"	Returns the version currently marked as staging (for canary testing).
"draft"	Returns the latest draft version (not yet promoted).
"latest"	Returns the highest version number regardless of status.
42 (integer)	Returns a specific version by number.

---

Examples

Fetch production prompt

import coalex

coalex.register(api_key="your-key")

prompt = coalex.get_prompt(agent="support-bot", name="system_message")
print(prompt.content)
# "You are a helpful customer support agent for Acme Corp..."
print(prompt.version)
# 3

A/B test with staging prompt

import random

version = "staging" if random.random() < 0.1 else "production"  # 10% canary
prompt = coalex.get_prompt(agent="support-bot", name="system_message", version=version)

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

Pin to a specific version

prompt = coalex.get_prompt(agent="claims-bot", name="extraction_prompt", version=7)
# Always returns version 7, regardless of which version is marked as production

---

Notes

• The API endpoint used is GET /api/v2/prompts/{agent}/{name}.
• Prompts are cached server-side. Fetching the same prompt repeatedly is fast.
• Use the Coalex dashboard's Prompt Vault visual editor to create, edit, and promote prompt versions.
• Network errors from the Coalex API raise httpx.HTTPStatusError.

---

API Reference

coalex.prompts.get_prompt

get_prompt(
    *,
    agent: str,
    name: str,
    version: str = "production",
    _config: CoalexConfig | None = None,
    _api_key: str | None = None,
) -> PromptVersion

Fetch a prompt template from the Prompt Vault.

Parameters:

Name	Type	Description	Default
agent	str	Agent ID (e.g., "sales-copilot").	required
name	str	Prompt name (e.g., "system").	required
version	str	"production" (default), "staging", "draft", "latest", or integer.	'production'
_config	CoalexConfig | None	Override config (testing only).	None
_api_key	str | None	Override API key (testing only).	None

Source code in coalex/prompts.py

def get_prompt(
    *,
    agent: str,
    name: str,
    version: str = "production",
    _config: CoalexConfig | None = None,
    _api_key: str | None = None,
) -> PromptVersion:
    """Fetch a prompt template from the Prompt Vault.

    Args:
        agent: Agent ID (e.g., "sales-copilot").
        name: Prompt name (e.g., "system").
        version: "production" (default), "staging", "draft", "latest", or integer.
        _config: Override config (testing only).
        _api_key: Override API key (testing only).
    """
    import coalex as _sdk

    cfg = _config or _sdk._config
    api_key = _api_key or _sdk._api_key
    if cfg is None:
        raise RuntimeError("coalex.register() must be called before get_prompt()")

    with httpx.Client(timeout=30.0) as client:
        resp = client.get(
            f"{cfg.endpoint}/api/v2/prompts/{agent}/{name}",
            params={"version": version},
            headers={"Authorization": f"Bearer {api_key}"},
        )
        resp.raise_for_status()

    data = resp.json()
    return PromptVersion(
        id=data["id"],
        agent_id=data["agent_id"],
        name=data["prompt_type"],
        prompt_type=data["prompt_type"],
        version=data["version"],
        content=data["content"],
        status=data["status"],
        metadata=data.get("metadata", {}),
    )