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

# Pi Coding Agent SDK

> Trace Pi Coding Agent SDK prompts, Anthropic LLM calls, and tool invocations in Braintrust

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.

The [Pi Coding Agent SDK](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (`@earendil-works/pi-coding-agent`) is a TypeScript SDK for running pi coding agents programmatically. Braintrust traces `AgentSession.prompt()` calls, Anthropic LLM calls, and tool invocations.

<Note>
  This page documents the `@earendil-works/pi-coding-agent` SDK. To trace interactive pi sessions with the Braintrust pi extension instead, see [pi](/integrations/developer-tools/pi).
</Note>

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

  Install Braintrust alongside the Pi Coding Agent SDK, then set your API keys. Requires `@earendil-works/pi-coding-agent` v0.79.x.

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        pnpm add braintrust @earendil-works/pi-coding-agent
        ```

        ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        npm install braintrust @earendil-works/pi-coding-agent
        ```
      </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>
      ANTHROPIC_API_KEY=<your-anthropic-api-key>
      ```
    </Step>
  </Steps>

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

  To trace Pi Coding Agent SDK runs without wrapping the SDK module yourself, initialize Braintrust normally, then run your app with Braintrust's import hook to patch the SDK at runtime.

  <Steps>
    <Step title="Initialize Braintrust and run a prompt">
      <CodeGroup>
        ```javascript title="trace-pi-coding-agent-auto.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        import { initLogger } from "braintrust";
        import {
          AuthStorage,
          ModelRegistry,
          SessionManager,
          createAgentSession,
        } from "@earendil-works/pi-coding-agent";

        initLogger({
          projectName: "pi-coding-agent-example", // Replace with your project name
          apiKey: process.env.BRAINTRUST_API_KEY,
        });

        const authStorage = AuthStorage.inMemory();
        authStorage.setRuntimeApiKey("anthropic", process.env.ANTHROPIC_API_KEY ?? "");

        const modelRegistry = ModelRegistry.inMemory(authStorage);
        modelRegistry.registerProvider("anthropic", {
          baseUrl: process.env.ANTHROPIC_BASE_URL,
        });
        const model = modelRegistry.find("anthropic", "claude-sonnet-4-5");
        if (!model) {
          throw new Error("Pi Coding Agent model not found");
        }

        const { session } = await createAgentSession({
          authStorage,
          cwd: process.cwd(),
          model,
          modelRegistry,
          sessionManager: SessionManager.inMemory(process.cwd()),
          thinkingLevel: "off",
          tools: ["bash"],
        });

        await session.prompt("Run `pwd` and summarize the result.", {
          expandPromptTemplates: false,
        });

        session.dispose?.();
        ```
      </CodeGroup>
    </Step>

    <Step title="Run with the import hook">
      ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      node --import braintrust/hook.mjs trace-pi-coding-agent-auto.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](/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup.
      </Note>
    </Step>
  </Steps>

  If you manage instrumentation hooks directly with `@braintrust/auto-instrumentations`, keep the Pi Coding Agent integration enabled.

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

  To trace the Pi Coding Agent SDK manually, wrap the imported module yourself with `wrapPiCodingAgentSDK()` before creating sessions.

  <CodeGroup>
    ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    import { initLogger, wrapPiCodingAgentSDK } from "braintrust";
    import * as pi from "@earendil-works/pi-coding-agent";

    initLogger({
      projectName: "pi-coding-agent-example", // Replace with your project name
      apiKey: process.env.BRAINTRUST_API_KEY,
    });

    const {
      AuthStorage,
      ModelRegistry,
      SessionManager,
      createAgentSession,
    } = wrapPiCodingAgentSDK(pi);

    const authStorage = AuthStorage.inMemory();
    authStorage.setRuntimeApiKey("anthropic", process.env.ANTHROPIC_API_KEY ?? "");

    const modelRegistry = ModelRegistry.inMemory(authStorage);
    modelRegistry.registerProvider("anthropic", {
      baseUrl: process.env.ANTHROPIC_BASE_URL,
    });
    const model = modelRegistry.find("anthropic", "claude-sonnet-4-5");
    if (!model) {
      throw new Error("Pi Coding Agent model not found");
    }

    const { session } = await createAgentSession({
      authStorage,
      cwd: process.cwd(),
      model,
      modelRegistry,
      sessionManager: SessionManager.inMemory(process.cwd()),
      thinkingLevel: "off",
      tools: ["bash"],
    });

    await session.prompt("Run `pwd` and summarize the result.", {
      expandPromptTemplates: false,
    });

    session.dispose?.();
    ```
  </CodeGroup>

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

  Braintrust patches `AgentSession.prompt()` and captures:

  * Task spans for each `AgentSession.prompt()` call.
  * Anthropic LLM spans nested under the prompt span, including model metadata, stop reasons, and token metrics.
  * Tool spans for tool invocations, including `bash` calls, tool names, inputs, outputs, and tool call IDs.
  * Pi Coding Agent metadata under keys such as `pi_coding_agent.operation`, `pi_coding_agent.api`, `pi_coding_agent.model`, `pi_coding_agent.source`, `pi_coding_agent.stop_reason`, and `pi_coding_agent.tool.name`.
  * OpenTelemetry GenAI tool metadata, including `gen_ai.tool.name` and `gen_ai.tool.call.id`.
  * Errors captured on task, LLM, and tool spans.

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

  * [Pi Coding Agent SDK on npm](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
  * [pi documentation](https://pi.dev)
</View>