Create prompts

Create prompts directly in the Braintrust UI or define them in code and push them with the SDK. Once created, extend prompts with tools and MCP servers, test them in playgrounds, and improve them with Loop.

Create a prompt

You can create a prompt in the UI or define it in code. Use the UI for quick, visual iteration, and use the SDK to version prompts alongside your application code and push them from your existing workflow.

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
- Tags: Optional labels for organizing and filtering prompts
- Metadata: Optional additional information
Click Save as custom prompt.

Prompt caching for Anthropic and Bedrock models

When using Anthropic or AWS Bedrock (Converse API) models, a cache control button appears on each message for Anthropic prompt caching. Click it to set a TTL of 5 minutes or 1 hour. When a message has multiple content blocks, you can set cache control on each block individually. Cache control settings are preserved when switching between Anthropic models and cleared when switching to a different provider.

Parameters for reasoning models

For reasoning models, the available parameters depend on the selected reasoning effort. GPT-5.1 and later expose a temperature setting only when Reasoning effort is none. Raising the reasoning effort removes the temperature setting. Older GPT-5 models (gpt-5, gpt-5-mini, gpt-5-nano) and GPT-5 Pro don’t accept temperature at any reasoning effort.

Define prompts in code, then push them to Braintrust with the bt CLI:

Define the prompt in code

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",
  tags: ["summarization"],
  model: "claude-sonnet-4-5-20250929",
  params: {
    temperature: 0.7,
    max_tokens: 1000,
    response_format: { type: "json_object" },
  },
  messages: [
    {
      role: "system",
      content: "You are a helpful assistant that can summarize text.",
    },
    {
      role: "user",
      content: "{{{text}}}",
    },
  ],
  metadata: { version: "1.0" },
});

import braintrust

project = braintrust.projects.create(name="Summarizer")

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

Assign an environment at creation time

To associate a prompt with a specific deployment environment in TypeScript, pass the environments field:

export const summarizer = project.prompts.create({
  name: "Summarizer",
  slug: "summarizer",
  environments: ["production"],
  messages: [{ role: "user", content: "{{{text}}}" }],
});

Python project.prompts.create(...) does not expose an environment-assignment parameter, so use the UI or API if you need to associate environments from Python.See Version prompts for details on assigning versions to environments.

Push to Braintrust

bt functions push summarizer.ts

bt functions push summarizer.py

To inject variables at runtime, use Mustache or Nunjucks templating in a prompt’s messages.

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 + Tool/MCP.
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-5-mini",
  messages: [
    {
      role: "system",
      content: "You are a helpful assistant that can answer questions about the Braintrust documentation.",
    },
    {
      role: "user",
      content: "{{{question}}}",
    },
  ],
  tools: [toolRAG],
});

import braintrust

project = braintrust.projects.create(name="RAG app")

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

When a prompt includes tools, your application code handles the tool calls returned at runtime. See Handle tool calls.

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.
Reuse existing MCP integrations without building custom tools.

MCP servers must be public, support OAuth authentication, and use http or https. To protect against server-side request forgery (SSRF), Braintrust validates the resolved target of each request.

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 + Tool/MCP.
Enable any of the project’s configured MCP servers.
To add a prompt-specific MCP server, click Configure MCP servers, then 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

Configure MCP servers at the project level so any prompt in the project can use them:

Go to Settings > 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.

Test prompts

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. You can also test prompts by chatting directly with them from the prompt details page. Each chat interaction is automatically logged as a trace in your project’s logs. To navigate back to the prompt from these traces, see Navigate to trace origins.

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

Keep these guidelines in mind as you write and refine a prompt’s messages: 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

Use templating to inject runtime variables with Mustache or Nunjucks.
Use prompts in code to invoke prompts from your application.
Version prompts to pin versions and assign them to environments.
Manage prompts to duplicate prompts and customize the Prompts page.
Use playgrounds for rapid iteration.
Write scorers to evaluate prompt quality.

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Create a prompt

Add tools

Add MCP servers

Add to a prompt

Add to a project

Test prompts

Optimize with Loop

Best practices

Next steps

​Create a prompt

​Add tools

​Add MCP servers

​Add to a prompt

​Add to a project

​Test prompts

​Optimize with Loop

​Best practices

​Next steps

Create a prompt

Add tools

Add MCP servers

Add to a prompt

Add to a project

Test prompts

Optimize with Loop

Best practices

Next steps