Skip to main content
Parameters let you create reusable configuration for your evaluations. Define parameters once in Braintrust, then load them across multiple evaluations. This approach enables:
  • Reusability: Share configurations across multiple evaluations
  • Centralized management: Update parameters in one place for all evaluations
  • Version control: Track parameter changes independently of evaluation code
  • Environment management: Use different parameter values across dev, staging, and production
Parameters require Braintrust TypeScript SDK v2.2.1 or later.

​
Create parameters

Define parameters in code and push to Braintrust:
eval-config.ts
import * as braintrust from "braintrust";
import { z } from "zod";

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

export const evalConfig = project.parameters.create({
  name: "Evaluation config",
  slug: "eval-config",
  description: "Configuration for model evaluation",
  schema: {
    model: z.string().default("gpt-5-mini").describe("Model to evaluate"),
    max_tokens: z.number().default(1000).describe("Maximum tokens to generate"),
    system_prompt: z.string().default("You are a helpful assistant.").describe("System prompt to use"),
  },
  metadata: { version: "1.0" },
});
Push to Braintrust: 
npx braintrust push eval-config.ts
When you create parameters with default values, Braintrust automatically initializes them with those defaults. This means the first version of your parameter will already have the default values set, ready to use in evaluations or modify in the UI.

​
Specify parameter types

Define the structure and types of your parameters using Zod (TypeScript). You can combine these building blocks to create any structure your evaluation needs, whether simple flat configurations or complex nested objects. These type definitions ensure your parameters have the correct data types and constraints. Building blocks for creating parameter schemas: 
import { z } from "zod";

// String with description
z.string().describe("Model name")

// Number with constraints
z.number().min(0).max(1).describe("Temperature")

// Boolean
z.boolean().describe("Enable streaming")

// Enum
z.enum(["gpt-5-mini", "gpt-5-nano", "claude-sonnet-4-5"]).describe("Model")

// Array
z.array(z.string()).describe("Test cases")

// Object
z.object({
  model: z.string(),
  temperature: z.number(),
}).describe("Model config")

// Optional with default
z.string().default("gpt-5-mini").describe("Model name")

​
Edit parameters

Update parameter values or schemas in the UI or in code. Every edit creates a new version automatically, preserving the history of changes.
  1. Go to Parameters.
  2. Select the parameters to edit.
  3. Modify values in the editor.
  4. Click Save version.
Every edit creates a new version automatically, preserving the history of changes.

​
Use in evaluations

Load parameters in your Eval() function using loadParameters(). Parameters are accessed in your task function via the parameters argument. For TypeScript type inference in your Eval’s task, pass your parameter type as a generic to loadParameters().
For remote evals, parameters automatically become editable controls in the playground UI, letting you modify values without changing code.
import { Eval, loadParameters } from "braintrust";
import { evalConfig } from "./eval-config";

Eval("My Project", {
  experimentName: "Parameter test",
  data: async () => [
    { input: "What is 2+2?", expected: "4" },
  ],
  task: async (input, { parameters }) => {
    return await callModel(input, {
      model: parameters.model,
      temperature: parameters.temperature,
    });
  },
  parameters: loadParameters<typeof evalConfig>({
    projectName: "My Project",
    slug: "eval-config",
  }),
});
When using loadParameters() in remote evals, the playground displays a version selector, letting you experiment with different parameter versions without editing code.

​
Pin to a version

Load a specific parameter version by ID: 
parameters: loadParameters({
  projectName: "My Project",
  slug: "eval-config",
  version: "5878bd218351fb8e",
})

​
Assign to an environment

To assign a specific parameter version to an environment:
  1. Go to Parameters.
  2. Open the parameter.
  3. Click the icon.
  4. Select an environment.
Once assigned, load parameters for that environment in your code: 
import { loadParameters } from "braintrust";

const params = await loadParameters({
  projectName: "My Project",
  slug: "eval-config",
  environment: "production",
});

​
Next steps