Source: Braintrust docs: Prompts
Braintrust prompt loading by slug, version and environment, build() without calling the model, version recording on spans, and cache fallback semantics.
Contents
- What: official product documentation
- Publisher: Braintrust
- Date: accessed 2026-11-14
- Original: docs.braintrust.dev/guides/functions/prompts
Summary
Braintrust stores prompts by slug and lets code load them by version or environment, render them locally, and record which version ran on each traced LLM span. Its SDK cache acts as a resilience fallback rather than a latency cache.
Key claims
- Prompts are referenced by slug; UI edits take effect without redeploying.
loadPrompt()(TS),load_prompt()(Python),client.LoadPrompt()(Go),Braintrust::Prompt.load()(Ruby);build()compiles to messages, model and parameters without calling the model;defaultssets fallback model params.- Loading by environment returns the version assigned to it; the
bt promptsCLI assigns versions to environments; a resolved version ID can be passed back to pin it exactly (the Ruby docs describeprompt.versionas the resolved version’s transaction ID; other SDKs only say the span records the prompt’s “ID and version”).invoke()logs inputs, outputs and the prompt version automatically. - Template variables like
{{text}}are filled from theinputparameter. - With a wrapped client (
wrap_openai/wrapOpenAI), the prompt’s ID and version are recorded in the LLM span’smetadata.prompt; loading alone logs nothing. For code-only prompts, log your own name/version/Git SHA in span metadata. - TS and Python fetch on every call and write an in-memory and disk cache; on transient errors (network, timeout, 429, 5xx) they return the last cached copy. Loads pinned to
versionorenvironmentnever fall back to the cache. Go does not cache.