Pi Coding Agent SDK

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.

Install packages

pnpm add braintrust @earendil-works/pi-coding-agent

npm install braintrust @earendil-works/pi-coding-agent

Set environment variables

.env

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.

Initialize Braintrust and run a prompt

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

Run with the import hook

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 with a TypeScript loader.

If you’re using a bundler, see Trace LLM calls 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.

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.

AI providers

SDKs

Developer tools

Runtime environments

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources

​Setup

​Auto-instrumentation

​Manual instrumentation

​What Braintrust traces

​Resources

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources