get_prompt()¶

Fetch a prompt template from the Coalex Prompt Vault: versioned prompts you can change without redeploying your agent, including a weighted canary that a share of "production" traffic is served.

There is no staging version

A version is draft or production, and promotion goes straight between the two; there is no staging state. The API answers a request for "staging" with 422. Python 1.34.0 and TypeScript 1.23.0 and later refuse it locally and say what the versions are. Canary testing is configured on the routing table and served under "production" — see Canary traffic below.

Signature¶

PythonTypeScript

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

function getPrompt(options: {
    agent: string;
    name: string;
    version?: "production" | "draft" | "latest" | number;
}): Promise<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"`, `"draft"`, `"latest"`, or a version number. Anything else raises `ValueError` (TypeScript: throws) without calling the API.

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" | "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"` or `"draft"`.
`metadata`	`dict \\| None`	Optional metadata attached to this prompt version.

Version Resolution¶

`version` parameter	Behavior
`"production"` (default)	Returns the version this agent's routing serves — the stable version, or the canary for its share of traffic. With no routing row, the highest version whose status is `production`.
`"draft"`	Returns the latest version whose status is `draft` (not yet promoted).
`"latest"`	Returns the highest version number, whatever its status.
`42` (integer)	Returns that version.

Anything else is refused by the SDK before the call, naming these: the API would answer 422, and a message from a service you are not looking at, about a value your own SDK's type accepted, is how "staging" cost people an afternoon.

Examples¶

Fetch production prompt¶

import coalex

coalex.register(endpoint="https://traces.coalex.ai", 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

Canary traffic¶

A canary is not something the agent asks for. Set a canary version and a weight on the agent's routing (PUT /api/v2/prompts/{agent}/{name}/traffic, or the dashboard's Prompt Vault editor), and the platform serves it to that share of "production" requests. The agent keeps asking for "production" and does not change:

prompt = coalex.get_prompt(agent="support-bot", name="system_message")  # "production"
print(prompt.version)
# 3 for most calls, 4 for the canary's share — `prompt.version` says which one you got

Because the version you were served is on the object, and the SDK stamps coalex.prompt_version on every span that follows, the two arms are separable in the dashboard without the agent knowing which arm it is in.

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

Prompt references¶

An instrumented LLM call records its prompt on the span, OpenInference twice (input.value and llm.input_messages.*), so a long system prompt makes every LLM span that size. A prompt fetched with get_prompt() is already in the Prompt Vault, so both SDKs (coalex 1.48 and later, @coalex-ai/sdk 2.10 and later) send a reference in its place by default. register(prompt_refs=False) (TypeScript: register({ promptRefs: false })), or COALEX_PROMPT_REFS=false, turns it off:

Where the whole text of a fetched prompt appears in input.value, llm.input_messages.* or the gen_ai.* input copies, it is replaced with the marker {{coalex.prompt.ref:<sha256>}}.
The span carries coalex.prompt.ref: a JSON array naming, for each prompt replaced, its vault id, version and sha256, and the attributes it was replaced in.
Coalex restores the text from your account's Prompt Vault when it stores the span, after checking the version and the hash. The trace view, the judge and the metrics read the span as it was instrumented.

What is not replaced, and is sent as before: a prompt formatted with variables or edited at runtime (its whole vault text no longer appears), a prompt that is not from the vault, and a prompt shorter than 256 characters. The span the agent's other exporters receive, such as a local Phoenix, keeps the text. With capture_content=False (TypeScript: captureContent: false) nothing is replaced, because no prompt text is exported.

What you see: smaller traces (an LLM span with a 72 KB system prompt is several times smaller on the wire) and the same governance data. The trace view, the judge and the metrics read the same input as without references, and your code does not change.

Needs a platform that restores references

References need a Coalex platform that restores them; Coalex SaaS does. Against a self-hosted platform that does not, the stored trace keeps the marker in place of the prompt (an operator's reprocess --force restores it later from the stored payload). Turn references off there.

To turn it off, pass register(prompt_refs=False) or set COALEX_PROMPT_REFS=0 (false, no and off also work); the SDK then exports the prompt text as before. The argument to register() wins over the environment variable.

TypeScript. register() turns references on unless you turn them off, so a customer who upgrades to @coalex-ai/sdk 2.10 changes no code and gets smaller traces with the same governance data. To export the prompt text in full, pass promptRefs: false or set COALEX_PROMPT_REFS to 0, false, no or off; the option wins over the variable. A prompt becomes a reference only when getPrompt() loaded it and the stored span can be restored byte for byte; every other prompt, and every prompt when captureContent is false, is exported as before. Against a self-hosted platform that does not restore references, pass promptRefs: false until it is upgraded.

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 | int = "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 \| int`	"production" (default), "draft", "latest", or a version number. Anything else raises `ValueError` — in particular "staging", which the Prompt Vault has never had, whatever older documentation said.	`'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 | int = "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), "draft", "latest", or a version number.
            Anything else raises ``ValueError`` — in particular "staging", which the Prompt
            Vault has never had, whatever older documentation said.
        _config: Override config (testing only).
        _api_key: Override API key (testing only).
    """
    import coalex as _sdk

    version = _checked_version(version)
    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/{path_segment(agent)}/{path_segment(name)}",
            params={"version": version},
            headers=sdk_headers(api_key),
        )
        raise_for_status(resp, "get_prompt()")

    data = resp.json()
    result = PromptVersion(
        id=data["id"],
        agent_id=data["agent_id"],
        # The Prompt Vault keys a prompt by (agent, prompt_type); there is no separate `name`
        # column, and the URL's `{name}` segment IS the prompt_type. So `name` mirrors it.
        name=data["prompt_type"],
        prompt_type=data["prompt_type"],
        version=data["version"],
        content=data["content"],
        status=data["status"],
        metadata=data.get("metadata", {}),
    )

    _record_prompt_version(result)
    return result