> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Eve

> Trace Eve agent sessions in Braintrust to observe LLM steps, tool calls, and subagent interactions

[Eve](https://eve.dev/) is a TypeScript agent runtime for building multi-turn agentic applications. Braintrust traces Eve agent sessions, turns, LLM steps, tool calls, and subagent interactions.

**TypeScript**

## Setup

Install `braintrust` alongside `eve` and set your Braintrust API key.

**1. Install packages**

```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
```

**2. Set environment variables**

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=<your-braintrust-api-key>
```

## Manual instrumentation

To trace Eve agents, add Braintrust instrumentation to your Eve agent. The setup depends on your Eve version:

* **Eve 0.62 or later**: Add one instrumentation file. See [Eve 0.62 or later](#eve-062-or-later-typescript).
* **Eve versions before 0.62**: Add a hook and a root `instrumentation.ts` file. See [Eve versions before 0.62](#eve-before-062-typescript).

### Eve 0.62 or later

Eve 0.62 and later load instrumentation from files under `agent/instrumentation/`. Requires `braintrust` v3.37.0 or later.

**1. Add Braintrust instrumentation**

Create a Braintrust instrumentation file. The `setup` callback runs once per agent process and initializes the Braintrust logger:

```typescript title="agent/instrumentation/braintrust.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { braintrustEveInstrumentation, initLogger } from "braintrust";

export default braintrustEveInstrumentation({
  metadata: {
    app: "my-eve-agent", // Replace with your app name
  },
  setup: ({ agentName }) => {
    initLogger({
      projectName: agentName, // Replace with your project name
      apiKey: process.env.BRAINTRUST_API_KEY,
    });
  },
});
```

Running `eve add instrumentation/braintrust` in your agent project creates this file.

**2. Build and run your agent**

Build and start your Eve agent. The Eve runtime loads the instrumentation file automatically:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
eve build && eve start
```

Eve versions 0.34 to 0.61 also support this setup if you set `experimental: { instrumentationProviders: true }` in `defineAgent()` in your `agent.ts`.

### Eve versions before 0.62

Eve versions before 0.62 load instrumentation from a root `instrumentation.ts` file. 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.

**1. Add a Braintrust hook**

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
    },
  }),
);
```

**2. 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:

```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,
      });
    },
  }),
);
```

**3. Build and run your agent**

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:

* Turn spans (`eve.turn`), as individual traces, with the user message as input, the agent's final response as output, and the session ID in metadata as `eve.session_id`. With the setup for Eve versions before 0.62, turn spans also have aggregated token metrics.
* Parent-child nesting under the caller's span, with the setup for Eve 0.62 or later, when the caller propagates W3C trace context to Eve. Eve forwards the caller's `traceparent` header for session requests that include a remote subagent `callback`. Requires `braintrust` v3.37.0 or later.
* 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. On Eve 0.72 and later, tool call spans require Braintrust v3.41.0 or later. Tool calls made by another tool nest under that tool.
* Subagent spans (named after the subagent), as tool spans nested under their turn, with the subagent's turn spans nested under them.
* Token usage metrics (prompt, completion, total, prompt cached, and prompt cache creation) on step spans. With the setup for Eve versions before 0.62, step spans also have estimated cost when Eve reports it.
* Errors captured on every span.

## Resources

* [Eve documentation](https://eve.dev/docs)
* [eve on npm](https://www.npmjs.com/package/eve)
* [Braintrust tracing guide](https://docs.braintrust.dev/instrument/trace-llm-calls.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.