Setup Install `braintrust` alongside `eve` and set your Braintrust API key. ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} pnpm add braintrust eve ``` ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} npm install braintrust eve ``` ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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. Create a hook file in your agent’s hooks directory. Eve loads hook files automatically at startup: ```typescript title="hooks/braintrust.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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 }, }), ); ``` Create an instrumentation file in your agent’s instrumentation directory. The `setup` callback runs once per agent process and initializes the Braintrust logger: ```typescript title="instrumentation.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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 start your Eve agent. The hook and instrumentation are loaded automatically by the Eve runtime: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} eve build && eve start ``` What Braintrust traces Braintrust captures: * Session spans (`eve.session`), as task spans, with metadata including the model and provider extracted from the agent runtime. * Turn spans (`eve.turn`), as task spans nested under their session, with the user message as input, the agent’s final response as output, and aggregated token metrics. * 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. Resources * [Eve documentation](https://eve.dev/docs) * [eve on npm](https://www.npmjs.com/package/eve) * [Braintrust tracing guide](/instrument/trace-llm-calls)