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

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](https://docs.braintrust.dev/integrations/developer-tools/pi.md).

**TypeScript**

## Setup

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

**1. Install packages**

```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
```

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

## Auto-instrumentation

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.

**1. Initialize Braintrust and run a prompt**

```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?.();
```

**2. 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 and run the compiled file with the import hook, or [run TypeScript directly](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) with a TypeScript loader.

> [!NOTE]
>
> If you're using a bundler, see [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) for plugin and loader setup.

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

## Manual instrumentation

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

```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?.();
```

## What Braintrust traces

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

* Task spans for each `AgentSession.prompt()` call.
* LLM spans nested under the prompt span, including input messages with the system prompt and later system prompt updates, declared tool schemas in `tools` metadata, model metadata, stop reasons, and token metrics. Token metrics appear only on LLM spans, so trace totals count each provider call once.
* Tool spans for tool invocations, including `bash` calls, tool names, inputs, outputs, and tool call IDs. A tool span records `metadata.tool_approval` as `approved` when the tool runs, so you can filter for tools that were allowed to run. Spans that your code creates while a tool runs nest under that tool's span.
* 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.

## Resources

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.