> ## Documentation Index
> Fetch the complete documentation index at: https://traceroot.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# pi SDK

> Trace embedded pi coding-agent sessions with TraceRoot

Automatically capture agent runs, LLM calls, tool executions, and token usage from [pi](https://pi.dev) coding-agent sessions you drive with `@earendil-works/pi-coding-agent` — the library form of pi, where you run an `AgentSession` from your own Node process instead of the interactive CLI.

<Note>
  Running the interactive `pi` CLI instead? Use the
  [TraceRoot pi extension](https://github.com/traceroot-ai/traceroot-pi-extension).
</Note>

## Setup

```bash theme={null}
npm install @traceroot-ai/traceroot @earendil-works/pi-coding-agent
```

Call `TraceRoot.initialize()` before creating any session:

```typescript theme={null}
import * as pi from '@earendil-works/pi-coding-agent';
import { TraceRoot } from '@traceroot-ai/traceroot';

TraceRoot.initialize({
  instrumentModules: { piCodingAgent: pi },
});
```

`@earendil-works/pi-coding-agent` is ESM-only and requires Node >=22.19.

## Usage

Create and run sessions as usual — every session created after initialization is traced automatically:

```typescript theme={null}
import { createAgentSession, ModelRegistry, ModelRuntime } from '@earendil-works/pi-coding-agent';

// pi 0.80's model + credential surface. Created async (it reads the on-disk
// model catalog), then handed to createAgentSession. Injecting OPENAI_API_KEY
// as a runtime credential authenticates from env alone — no `pi auth login`.
const modelRuntime = await ModelRuntime.create();
await modelRuntime.setRuntimeApiKey('openai', process.env.OPENAI_API_KEY);

const modelRegistry = new ModelRegistry(modelRuntime);
const model = modelRegistry.find('openai', 'gpt-4o-mini');

const { session } = await createAgentSession({ model, modelRuntime });
try {
  await session.prompt('Write add.js exporting add(a, b), then write and run a test for it.');
} finally {
  session.dispose();
}
```

Each `session.prompt()` becomes a nested trace, with tool spans under the LLM span that requested them:

```
AgentSession.prompt              # AGENT span — one per prompt() call
└── gpt-4o-mini                  # LLM span — provider, tokens
    ├── write: add.js            # TOOL span — arguments + result
    ├── write: test-add.js
    └── bash: node test-add.js
```

## What Gets Captured

| Attribute  | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| Agent runs | One span per `session.prompt()` call                           |
| Model      | Model id for each LLM call                                     |
| Messages   | Prompt and assistant response, when content capture is enabled |
| Tool calls | Each tool execution with arguments, result, and error status   |
| Tokens     | Input, output, and cache read/write counts                     |
| Latency    | Duration per span                                              |

`captureContent` and `captureToolIo` (both default `true`) control whether prompt/response text and tool arguments/results are attached to spans. Pass them through the `{ module, config }` form:

```typescript theme={null}
TraceRoot.initialize({
  instrumentModules: {
    piCodingAgent: { module: pi, config: { captureContent: false, captureToolIo: false } },
  },
});
```

## Run the example

<Card title="TypeScript" icon="js" href="https://github.com/traceroot-ai/traceroot/tree/main/examples/typescript/pi-agent-sdk">
  Run a complete session end-to-end.
</Card>