> ## 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](/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, such as ad-hoc lookups and exploration from your IDE.

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

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

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

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