Eve

Setup

Install braintrust alongside eve and set your Braintrust API key.

Install packages

pnpm add braintrust eve

npm install braintrust eve

Set environment variables

.env

BRAINTRUST_API_KEY=<your-braintrust-api-key>

Manual instrumentation

To trace Eve agents, register a Braintrust hook and instrumentation in your Eve agent. The hook handles the full span lifecycle; the instrumentation initializes the logger and captures LLM inputs for step spans.

Add a Braintrust hook

Create a hook file in your agent’s hooks directory. Eve loads hook files automatically at startup:

hooks/braintrust.ts

import { braintrustEveHook } from "braintrust";
import { defineState } from "eve/context";
import { defineHook } from "eve/hooks";

export default defineHook(
  braintrustEveHook({
    defineState,
    metadata: {
      app: "my-eve-agent", // Replace with your app name
    },
  }),
);

Add Braintrust instrumentation

Create an instrumentation file in your agent’s instrumentation directory. The setup callback runs once per agent process and initializes the Braintrust logger:

instrumentation.ts

import { braintrustEveInstrumentation, initLogger } from "braintrust";
import { defineState } from "eve/context";
import { defineInstrumentation } from "eve/instrumentation";

export default defineInstrumentation(
  braintrustEveInstrumentation({
    defineState,
    setup: ({ agentName }) => {
      initLogger({
        projectName: agentName, // Replace with your project name
        apiKey: process.env.BRAINTRUST_API_KEY,
      });
    },
  }),
);

Build and run your agent

Build and start your Eve agent. The hook and instrumentation are loaded automatically by the Eve runtime:

eve build && eve start

What Braintrust traces

Braintrust captures:

Turn spans (eve.turn), as individual traces, with the user message as input, the agent’s final response as output, aggregated token metrics, and the session ID in metadata as eve.session_id.
Step spans (eve.step), as LLM spans nested under their turn, with the full message history as input, the model response as output, and model name and provider in metadata.
Tool call spans (named after the tool), as tool spans nested under their turn, with the tool arguments as input and the tool result as output.
Subagent spans (named after the subagent), as tool spans nested under their turn, with the subagent input and output.
Token usage metrics (prompt, completion, total, prompt cached, prompt cache creation, and estimated cost) on step spans.
Errors captured on every span.

AI providers

SDKs

Developer tools

Setup

Manual instrumentation

What Braintrust traces

Resources

​Setup

​Manual instrumentation

​What Braintrust traces

​Resources

Setup

Manual instrumentation

What Braintrust traces

Resources