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

# OpenRouter Agent

> Trace OpenRouter Agent calls with Braintrust

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.

[`@openrouter/agent`](https://www.npmjs.com/package/@openrouter/agent) is OpenRouter's TypeScript agent toolkit for agent loops.

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

    <Steps>
      <Step title="Install packages">
        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        # pnpm
        pnpm add braintrust @openrouter/agent
        # npm
        npm install braintrust @openrouter/agent
        ```
      </Step>

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

        # If you are self-hosting Braintrust, set the URL of your hosted dataplane
        # BRAINTRUST_API_URL=<your-braintrust-api-url>
        ```
      </Step>
    </Steps>

    Braintrust supports `@openrouter/agent` v0.1.2 and later.

    <h2 id="auto-instrumentation-typescript">
      Auto-instrumentation
    </h2>

    Braintrust can auto-instrument `OpenRouter.callModel()` calls. This is the recommended setup for most projects.

    <CodeGroup>
      ```javascript title="app.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      import { initLogger } from "braintrust";
      import { OpenRouter } from "@openrouter/agent";

      initLogger({
        projectName: "My Project",
        apiKey: process.env.BRAINTRUST_API_KEY,
      });

      const client = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
      const result = client.callModel({
        model: "openai/gpt-5-mini",
        input: "What is observability?",
      });

      const text = await result.getText();
      ```
    </CodeGroup>

    Run with the import hook:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    node --import braintrust/hook.mjs app.js
    ```

    The auto-instrumentation example uses plain JavaScript so `node --import` can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook.

    <Note>
      If you're using a bundler, see [Trace LLM calls](/docs/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup.
    </Note>

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

    Trace an OpenRouter Agent client explicitly by wrapping it with `wrapOpenRouterAgent`.

    <CodeGroup>
      ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      import { initLogger, wrapOpenRouterAgent } from "braintrust";
      import { OpenRouter } from "@openrouter/agent";

      initLogger({
        projectName: "My Project",
        apiKey: process.env.BRAINTRUST_API_KEY,
      });

      const client = wrapOpenRouterAgent(
        new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY }),
      );

      const result = client.callModel({
        model: "openai/gpt-5-mini",
        input: "Reply with exactly: traced",
      });

      const text = await result.getText();
      ```
    </CodeGroup>

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

    Braintrust captures the agent run as a trace tree:

    * A top-level LLM span for the call, with the final output and aggregated token usage across all turns.
    * One nested LLM span per agent loop turn, with per-turn input, output, and usage, plus `step` and `step_type` (`initial` or `continue`) metadata.
    * One tool span per tool invocation the agent makes, with the tool name, input, and output.
  </Tab>
</Tabs>