> ## 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](/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.

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](/docs/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.0 or later.

  <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](/docs/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>