Write effective prompts

Prompts are the instructions that guide model behavior. Braintrust lets you create prompts, test them in playgrounds, use them in code, and track their performance over time.

Create prompts

Create prompts directly in the Braintrust UI:

Go to Prompts and click + Prompt
Configure the prompt:
- Name: Descriptive display name
- Slug: Unique identifier for code references (remains constant across updates)
- Model and parameters: Model selection, temperature, max tokens, etc.
- Messages: System, user, assistant, or tool messages with text or images
- Templating syntax: Mustache or Nunjucks for variable substitution
- Response format: Freeform text, JSON object, or structured JSON schema
- Description: Optional context about the prompt’s purpose
- Metadata: Optional additional information
Click Save as custom prompt

Define prompts in code and push to Braintrust:

summarizer.ts

import * as braintrust from "braintrust";

const project = braintrust.projects.create({
  name: "Summarizer",
});

export const summarizer = project.prompts.create({
  name: "Summarizer",
  slug: "summarizer",
  description: "Summarize text",
  model: "claude-sonnet-4-5-20250929",
  temperature: 0.7,
  max_tokens: 1000,
  messages: [
    {
      role: "system",
      content: "You are a helpful assistant that can summarize text.",
    },
    {
      role: "user",
      content: "{{{text}}}",
    },
  ],
  response_format: { type: "json_object" },
  metadata: { version: "1.0" },
});

Push to Braintrust:

npx braintrust push summarizer.ts

braintrust push summarizer.py

Use templating

Use templates to inject variables into prompts at runtime. Braintrust supports Mustache and Nunjucks templating:

Mustache (default): Simple variable substitution and basic logic
Nunjucks: Advanced templating with loops, conditionals, and filters

Nunjucks is a UI-only feature. It works in playgrounds but not when invoked via SDK.

Mustache

Mustache is the default templating language.

Basic variable substitution

Use {{variable}} to insert values:

Hello {{name}}! Your account balance is ${{balance}}.

Nested properties

Access nested object properties with dot notation:

User: {{user.name}}
Email: {{user.profile.email}}
City: {{user.profile.address.city}}

Sections and iteration

Use sections to iterate over arrays or conditionally show content:

{{#items}}
- {{name}}: ${{price}}
{{/items}}

{{#user}}
Welcome back, {{name}}!
{{/user}}

Inverted sections

Use ^ to show content when a value is falsy or empty:

{{^items}}
No items found.
{{/items}}

Comments

Use {{! comment }} for comments that won’t appear in output:

{{! This is a comment explaining the template }}
Hello {{name}}!

Preserve special characters

If you want to preserve double curly brackets {{ and }} as plain text when using Mustache, change the delimiter tags:

{{=<% %>=}}
Return the number in the following format: {{ number }}

<% input.formula %>

Strict mode

Mustache supports strict mode, which throws an error when required template variables are missing:

const result = prompt.build(
  { name: "Alice" },
  {
    strict: true, // Throws if any required variables are missing
  },
);

Nunjucks

For more complex templating needs, use Nunjucks, which implements Jinja2 syntax in JavaScript.

Nunjucks is a UI-only feature. It works in playgrounds but not when invoked via SDK.

Loops

Process arrays and iterate over data:

{% for item in items %}
- {{ item.name }}: {{ item.description }}
{% endfor %}

Loop variables provide useful metadata:

{% for product in products %}
{{ loop.index }}. {{ product.name }}{% if not loop.last %}, {% endif %}
{% endfor %}

Available loop variables: loop.index (1-indexed), loop.index0 (0-indexed), loop.first, loop.last, loop.length

Conditionals

Add logic to your prompts:

{% if user.age >= 18 %}
You are eligible to vote.
{% elif user.age >= 16 %}
You can get a driver's license.
{% else %}
You are a minor.
{% endif %}

Combine conditionals with loops:

{% for product in products %}
  {% if product.inStock %}
Available: {{ product.name }} - ${{ product.price }}
  {% endif %}
{% endfor %}

Filters

Transform data with built-in filters:

Hello {{ name | upper }}!
Your email is {{ email | lower }}.
Items: {{ items | join(", ") }}

Common filters:

upper, lower: Change case
title, capitalize: Capitalize text
join(separator): Join array elements
length: Get array or string length
default(value): Provide default value
replace(old, new): Replace text

String operations

Concatenate strings with ~:

{{ greeting ~ " " ~ name }}!
Full name: {{ firstName ~ " " ~ lastName }}

Nested data access

Access nested properties and array elements:

{{ user.profile.address.city }}
{{ items[0].name }}
{{ data.results[2].score }}

For complete Mustache syntax, see the Mustache documentation. For Nunjucks syntax and features, see the Nunjucks templating documentation.

Add tools

Tools extend your prompt’s capabilities by allowing the LLM to call functions during execution:

Query external APIs or databases
Perform calculations or data transformations
Retrieve information from vector stores or search engines
Execute custom business logic

To add tools to a prompt in the UI:

When creating or editing a prompt, click Tools.
Select tool functions from your library or add raw tools as JSON.
Click Save tools.

To add tools to a prompt in code, use the tools parameter:

import * as braintrust from "braintrust";

const project = braintrust.projects.create({
  name: "RAG app",
});

export const docSearch = project.prompts.create({
  name: "Doc Search",
  slug: "document-search",
  model: "gpt-4o-mini",
  messages: [
    {
      role: "system",
      content: "You are a helpful assistant that can answer questions about the Braintrust documentation.",
    },
    {
      role: "user",
      content: "{{{question}}}",
    },
  ],
  tools: [toolRAG],
});

Add MCP servers

Use public MCP (Model Context Protocol) servers to give your prompts access to external tools and data:

Evaluate complex tool calling workflows
Experiment with external APIs and services
Tune public MCP servers

MCP servers must be public and support OAuth authentication.

MCP servers are a UI-only feature. They work in playgrounds and experiments but not when invoked via SDK.

Add to a prompt

To add an MCP server to a prompt:

When creating or editing a prompt, click MCP.
Enable any available project-wide servers.
To add a prompt-specific MCP server, click + MCP server:
- Provide a name, the public URL of the server, and an optional description.
- Click Add server.
- Authenticate the MCP server in your browser.

For each MCP server, you’ll see a list of available tools. Tools are enabled by default, but you can disable individual tools or click Disable all. After testing a prompt-specific MCP server, you can promote it to a project-wide server by clicking … > Save to project MCP servers.

Add to a project

Project-wide MCP servers are accessible across all projects in your organization:

Go to Configuration > MCP.
Click + MCP server and provide a name, the public URL of the server, and an optional description.
Click Authenticate to authenticate the MCP server in your browser.
Click Save.

Use in code

Reference prompts by slug to use them in your application:

import { initLogger } from "braintrust";

const logger = initLogger({ projectName: "My Project" });

const result = await logger.invoke("summarizer", {
  input: { text: "Long article text here..." },
});

console.log(result.output);

Using prompts this way:

Automatically logs inputs and outputs
Tracks which prompt version was used
Enables A/B testing different prompt versions
Lets you update prompts without code changes

Load a prompt

The loadPrompt()/load_prompt() function loads a prompt with caching support:

import { OpenAI } from "openai";
import { initLogger, loadPrompt, wrapOpenAI } from "braintrust";

const logger = initLogger({ projectName: "My Project" });
const client = wrapOpenAI(new OpenAI());

async function runPrompt() {
  const prompt = await loadPrompt({
    projectName: "My Project",
    slug: "summarizer",
    defaults: {
      model: "gpt-4o",
      temperature: 0.5,
    },
  });

  return client.chat.completions.create(
    prompt.build({ text: "Article to summarize..." }),
  );
}

Pin a specific version

Reference a specific version when loading prompts:

const prompt = await loadPrompt({
  projectName: "My Project",
  slug: "summarizer",
  version: "5878bd218351fb8e",
});

Stream results

Stream prompt responses for real-time output:

import { invoke } from "braintrust";

async function main() {
  const result = await invoke({
    projectName: "My Project",
    slug: "summarizer",
    input: { text: "Article text..." },
    stream: true,
  });

  for await (const chunk of result) {
    console.log(chunk);
    // { type: "text_delta", data: "The summary "}
    // { type: "text_delta", data: "is..."}
  }
}

Add extra messages

Append additional messages to prompts for multi-turn conversations:

import { invoke } from "braintrust";

async function reflection(question: string) {
  const result = await invoke({
    projectName: "My Project",
    slug: "assistant",
    input: { question },
  });

  const reflectionResult = await invoke({
    projectName: "My Project",
    slug: "assistant",
    input: { question },
    messages: [
      { role: "assistant", content: result },
      { role: "user", content: "Are you sure about that?" },
    ],
  });

  return reflectionResult;
}

Test in playgrounds

Playgrounds provide a no-code environment for rapid prompt iteration:

Create or select a prompt
Add a dataset or enter test inputs
Run the prompt and view results
Adjust parameters or messages
Compare different versions side-by-side

See Use playgrounds for details.

Version prompts

Every prompt change creates a new version automatically. This lets you:

Compare performance across versions
Roll back to previous versions
Pin experiments to specific versions
Track which version is used in production

View version history in the prompt editor and select any version to restore or compare.

Optimize with Loop

Use Loop to generate and improve prompts: Example queries:

“Generate a prompt for a chatbot that can answer questions about the product”
“Add few-shot examples based on project logs”
“Optimize this prompt to be friendlier and more engaging”
“Improve this prompt based on the experiment results”

Loop analyzes your data and suggests improvements automatically.

Best practices

Start simple: Begin with clear, direct instructions. Add complexity only when needed. Use few-shot examples: Include 2-3 examples in your prompt to guide model behavior. Be specific: Define exactly what you want, including format, tone, and constraints. Test with real data: Use production logs to build test datasets that reflect actual usage. Iterate systematically: Change one thing at a time and measure impact with experiments. Version everything: Save prompt changes so you can track what works and roll back if needed.

Next steps

Write scorers to evaluate prompt quality
Run evaluations to compare prompt versions
Use playgrounds for rapid iteration
Use the Loop to optimize prompts

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Write effective prompts

Create prompts

Use templating

Mustache

Nunjucks

Add tools

Add MCP servers

Add to a prompt

Add to a project

Use in code

Load a prompt

Pin a specific version

Stream results

Add extra messages

Test in playgrounds

Version prompts

Optimize with Loop

Best practices

Next steps

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

​Create prompts

​Use templating

​Mustache

​Nunjucks

​Add tools

​Add MCP servers

​Add to a prompt

​Add to a project

​Use in code

​Load a prompt

​Pin a specific version

​Stream results

​Add extra messages

​Test in playgrounds

​Version prompts

​Optimize with Loop

​Best practices

​Next steps

Create prompts

Use templating

Mustache

Nunjucks

Add tools

Add MCP servers

Add to a prompt

Add to a project

Use in code

Load a prompt

Pin a specific version

Stream results

Add extra messages

Test in playgrounds

Version prompts

Optimize with Loop

Best practices

Next steps