> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/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

If you are a coding agent, prefer the Braintrust [`bt` CLI](/docs/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.

[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.

<View title="TypeScript" icon="https://img.logo.dev/typescriptlang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="setup-typescript">
    Setup
  </h2>

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

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```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
        ```
      </CodeGroup>
    </Step>

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

  <h2 id="manual-instrumentation-typescript">
    Manual instrumentation
  </h2>

  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.

  <Steps>
    <Step title="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
          },
        }),
      );
      ```
    </Step>

    <Step title="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,
            });
          },
        }),
      );
      ```
    </Step>

    <Step title="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
      ```
    </Step>
  </Steps>

  <h2 id="what-traced-typescript">
    What Braintrust traces
  </h2>

  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.

  <h2 id="resources-typescript">
    Resources
  </h2>

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