Skip to main content
A prompt is the set of instructions, model, and parameters that define how an LLM behaves for a task. In Braintrust, prompts are versioned objects you can build in the UI or SDK, iterate on in playgrounds, and call from your application code. For example, a summarization prompt pairs a system instruction with a templated user message:
You author this once in Braintrust, then call it from your application by its slug, passing a text value at runtime. Braintrust runs the prompt against its configured model and logs the call, so you can change the wording, model, or parameters from the UI without redeploying your application. Key advantages:
  • Versioned: Every change to a prompt creates a new version, so you can compare, roll back, and pin experiments or production to a specific version.
  • Decoupled from code: Update a prompt in the UI and the change takes effect in production immediately, without redeploying your application.
  • Controlled: Pin a version in code or assign versions to environments so a change reaches production only when you intend.
  • Testable: Iterate in playgrounds, chat with a prompt directly, and optimize it with Loop.

​
How a prompt reaches your application

  1. You create a prompt in Braintrust, either in the UI or by defining it in code and pushing it with the bt CLI. Each save creates a new version.
  2. Your application asks for the prompt by slug. It gets the latest version, a version you pinned, or the version assigned to an environment.
  3. Your application runs it, either by invoking it on Braintrust, where Braintrust calls the model and logs the result, or by loading it and building the messages locally to call with your own LLM client.
Nothing is pushed out to your application. It pulls the prompt at runtime, which is why a UI edit can change behavior without a redeploy.

​
Prompt anatomy

A prompt is made up of the following parts:
  • Name and slug: A display name plus a slug (a stable identifier you reference from code that stays constant across updates).
  • Model and parameters: The model to call and settings like temperature and max tokens.
  • Messages: System, user, assistant, or tool messages containing text or images.
  • Templating: Mustache or Nunjucks syntax that injects variables into messages at runtime.
  • Response format: Freeform text, a JSON object, or a structured JSON schema.
  • Tools and MCP servers: Functions or MCP servers the model can call during execution.
Prompts can also carry an optional description, tags, and metadata for organizing and filtering.

​
Where to go from here

  • Create prompts in the UI or SDK, add tools and MCP servers, and optimize them with Loop.
  • Use templating to inject runtime variables with Mustache or Nunjucks.
  • Use prompts in code by invoking them by slug, building them locally, handling tool calls, and calling the REST API.
  • Version prompts by pinning versions and assigning them to environments.
  • Manage prompts by duplicating them and customizing the Prompts page.
To test and compare prompts in a no-code environment, see Playgrounds.