Use prompts in code

Prompts created in Braintrust can be called directly from your application code. Reference a prompt by its slug, and changes you make in the UI take effect immediately without redeploying your application.

Two ways to run a prompt

Your application can run a prompt in one of two ways, which differ in where the model call happens and what you get back:

Invoke it on Braintrust. invoke() runs the prompt against its configured model and returns the model’s response. Braintrust makes the model call and logs it.
Load it and run it yourself. loadPrompt() fetches the prompt’s configuration, and build() compiles it into request parameters that you pass to your own LLM client.

The return values make the difference concrete. For the same summarizer prompt:

{
  "model": "gpt-5-mini",
  "temperature": 0.5,
  "messages": [
    { "role": "system", "content": "You are a helpful assistant that summarizes text." },
    { "role": "user", "content": "Summarize the following text: Long text to summarize..." }
  ]
}

"The article argues that evaluation, not model choice, is the bottleneck in shipping AI features."

Invoke a prompt when you want Braintrust to run and log the call for you. Load a prompt when you need to make the model call yourself, either to use a provider client you already have configured or to inspect or change the messages before sending them.

Invoke a prompt

invoke() runs a prompt on Braintrust using its configured model and parameters, and returns the model’s response. Call it by slug:

import { invoke } from "braintrust";

const result = await invoke({
  projectName: "My Project",
  slug: "summarizer",
  input: {
    text: "Long text to summarize...",
  },
});

console.log(result);

The input parameter values map to template variables in your prompt. For example, {{text}} in your prompt gets replaced with the text value from input. Invoking 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.

The Ruby SDK doesn’t support server-side invocation. Instead, load a prompt and build it locally, then call your own LLM client. See Load a prompt.

To pin a specific version or load the version assigned to an environment, see Version prompts.

Load a prompt

Use loadPrompt() (TypeScript), load_prompt() (Python), or client.LoadPrompt() (Go) to fetch a prompt’s configuration, then call build() on the result to compile its template into request parameters for your own LLM client:

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-5-mini",
      temperature: 0.5,
    },
  });

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

from braintrust import init_logger, load_prompt, wrap_openai
from openai import OpenAI

logger = init_logger(project="My Project")
client = wrap_openai(OpenAI())

def run_prompt():
    prompt = load_prompt(
        "My Project",
        "summarizer",
        defaults=dict(model="gpt-5-mini", temperature=0.5)
    )

    return client.chat.completions.create(
        **prompt.build(text="Article to summarize...")
    )

import (
	"context"

	"github.com/braintrustdata/braintrust-sdk-go"
	"github.com/braintrustdata/braintrust-sdk-go/prompt"
	traceopenai "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/openai"
	openai "github.com/openai/openai-go"
	"go.opentelemetry.io/otel/sdk/trace"
)

func runPrompt(ctx context.Context) error {
	bt, err := braintrust.New(trace.NewTracerProvider(), braintrust.WithProject("My Project"))
	if err != nil {
		return err
	}

	p, err := bt.LoadPrompt(ctx, prompt.LoadOpts{Slug: "summarizer"})
	if err != nil {
		return err
	}

	built, err := p.Build(map[string]any{"text": "Article to summarize..."})
	if err != nil {
		return err
	}

	params, err := traceopenai.ChatCompletionParams(built)
	if err != nil {
		return err
	}

	_, err = openai.NewClient().Chat.Completions.New(ctx, params)
	return err
}

require "braintrust"

prompt = Braintrust::Prompt.load(
  project: "My Project", # Or project_id: "your-project-uuid"
  slug: "summarizer"
)

params = prompt.build(text: "Long text to summarize...")

puts params[:messages]
# Pass params to your own LLM client, e.g. openai.chat.completions.create(**params)

build() returns the compiled messages, model, and parameters without calling the model, so you can pass them straight to a client or inspect them first. The TypeScript and Python functions cache the loaded prompt in memory and on disk, so repeated loads skip the network round trip and fall back to the last cached copy if Braintrust is unreachable. The Go client.LoadPrompt() method fetches the prompt on every call. Unlike invoke(), loading a prompt doesn’t log anything on its own. Braintrust records the call only if the client you pass the messages to is instrumented, which is why the examples above wrap the client with wrapOpenAI()/wrap_openai(). See Trace LLM calls for the instrumentation options in each language.

In Ruby, identify the project by name (project:) or by UUID (project_id:). Providing neither raises an ArgumentError. After loading, prompt.version returns the resolved version’s transaction ID, which you can pass to Braintrust::Prompt.load(version:) to re-pin the exact same version later.

For the full Go prompt surface, including inline prompt.Definition prompts and built.AnnotateSpan for trace linkage, see the Go API reference.

Use within a trace

When calling prompts from instrumented code, they automatically nest within your parent trace:

import { initLogger, traced } from "braintrust";

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

const summarize = traced(async (text: string) => {
  return await logger.invoke("summarizer", { input: { text } });
});

// This creates a trace with "summarize" as parent
const result = await summarize("Long text to summarize...");

from braintrust import init_logger, traced

logger = init_logger(project_name="My Project")

@traced
async def summarize(text: str):
    return await logger.invoke("summarizer", input={"text": text})

# This creates a trace with "summarize" as parent
result = await summarize("Long text to summarize...")

This creates a hierarchical trace where the prompt execution appears as a child span of your function.

Handle tool calls

When a prompt includes tools, the response contains tool calls that your code must handle:

import { invoke } from "braintrust";

const result = await invoke({
  projectName: "RAG App",
  slug: "document-search",
  input: { question: "What is Braintrust?" },
});

// Handle tool calls
if (result.toolCalls) {
  for (const toolCall of result.toolCalls) {
    console.log(`Tool: ${toolCall.function.name}`);
    console.log(`Arguments: ${toolCall.function.arguments}`);
    // Execute tool and return results...
  }
}

from braintrust import invoke

result = invoke(
    project_name="RAG App",
    slug="document-search",
    input={"question": "What is Braintrust?"},
)

# Handle tool calls
if hasattr(result, "tool_calls"):
    for tool_call in result.tool_calls:
        print(f"Tool: {tool_call.function.name}")
        print(f"Arguments: {tool_call.function.arguments}")
        # Execute tool and return results...

See Add tools to attach tools to a prompt, and Deploy functions for details on deploying tools alongside prompts.

Add extra messages

The messages parameter appends messages after the prompt’s own messages, letting you continue a conversation while reusing the prompt’s model and configuration. The example below invokes the assistant prompt, then invokes it again with the model’s first answer and a follow-up question so it can reconsider its response:

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;
}

from braintrust import invoke

def reflection(question: str):
    result = invoke(
        project_name="My Project",
        slug="assistant",
        input={"question": question},
    )

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

    return reflection_result

Stream responses

Set stream: true to receive responses incrementally:

import { invoke } from "braintrust";

const stream = await invoke({
  projectName: "My Project",
  slug: "summarizer",
  input: { text: "Long text to summarize..." },
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

from braintrust import invoke

stream = invoke(
    project_name="My Project",
    slug="summarizer",
    input={"text": "Long text to summarize..."},
    stream=True,
)

for chunk in stream:
    print(chunk, end="")

Streaming works automatically through the Gateway and logs the complete response to Braintrust. For the Server-Sent Events format and streaming through the Gateway or wrapped clients, see Stream responses.

Manage from the CLI

Use the bt CLI to browse and test prompts without opening the UI. Browse prompts:

bt prompts list                   # List all prompts in the active project
bt prompts view summarizer        # View a specific prompt's definition
bt prompts versions summarizer    # List a prompt's versions

Test a prompt: Use bt functions invoke to call a prompt and see its output directly from the terminal:

bt functions invoke --slug summarizer --input '{"text": "Long text to summarize..."}'

See bt prompts for the full command surface, including assigning a prompt version to an environment.

Use the REST API

Call prompts directly via HTTP.

In the examples below, organizations on the EU data plane should replace api.braintrust.dev with api-eu.braintrust.dev.

curl https://api.braintrust.dev/v1/function \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -d '{
    "project_name": "My Project",
    "slug": "summarizer",
    "input": {
      "text": "Long text to summarize..."
    }
  }'

The REST API supports all the same parameters as the SDK, including versioning, environments, and streaming.

Next steps

Version prompts to pin versions and assign them to environments.
Stream responses to return incremental output from prompts and functions.
Deploy functions to deploy tools and workflows alongside prompts.
Monitor deployments to track prompt performance in production.

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Two ways to run a prompt

Invoke a prompt

Load a prompt

Use within a trace

Handle tool calls

Add extra messages

Stream responses

Manage from the CLI

Use the REST API

Next steps

​Two ways to run a prompt

​Invoke a prompt

​Load a prompt

​Use within a trace

​Handle tool calls

​Add extra messages

​Stream responses

​Manage from the CLI

​Use the REST API

​Next steps

Two ways to run a prompt

Invoke a prompt

Load a prompt

Use within a trace

Handle tool calls

Add extra messages

Stream responses

Manage from the CLI

Use the REST API

Next steps