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

# Pi Agent (Beta)

> Automatic observability for Pi — the pi.dev coding agent and agent harness — with Raindrop

The `@raindrop-ai/pi-agent` package automatically instruments [Pi](https://pi.dev) (the agent harness and coding agent from [pi.dev](https://pi.dev), source at [earendil-works/pi](https://github.com/earendil-works/pi)) to capture events, traces, and tool calls. Works with both the programmatic `pi-agent-core` API and the Pi Coding Agent CLI.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @raindrop-ai/pi-agent
  ```

  ```bash pnpm theme={null}
  pnpm add @raindrop-ai/pi-agent
  ```
</CodeGroup>

## Quick Start — Programmatic

```typescript theme={null}
import { Agent } from "@earendil-works/pi-agent-core";
import { getModel } from "@earendil-works/pi-ai";
import { createRaindropPiAgent } from "@raindrop-ai/pi-agent";

const raindrop = createRaindropPiAgent({
  writeKey: "your-write-key",
  userId: "user-123",
  convoId: "session-abc",
});

const agent = new Agent({
  initialState: {
    systemPrompt: "You are a helpful assistant.",
    model: getModel("openai", "gpt-4o-mini"),
  },
});

raindrop.subscribe(agent);

await agent.prompt("What is the capital of France?");
await raindrop.shutdown();
```

## Quick Start — Pi Coding Agent CLI

```bash theme={null}
pi install npm:@raindrop-ai/pi-agent
```

Set `RAINDROP_WRITE_KEY` in your environment. Traces appear automatically.

Or configure via `~/.pi/agent/raindrop.json`:

```json theme={null}
{
  "write_key": "your-write-key",
  "capture_system_prompt": true
}
```

## Configuration

```typescript theme={null}
const raindrop = createRaindropPiAgent({
  writeKey: "your-write-key",                        // Optional — omit to disable
  userId: "user-123",
  convoId: "session-abc",
  projectId: "support-prod",                 // Optional: route events to a specific project (slug)
  eventName: "pi_agent_prompt",              // Default event name
  properties: { environment: "production" },

  events: { enabled: true, debug: false },
  traces: { enabled: true, debug: false },
});
```

### Per-Subscribe Overrides

Override context per subscription when tracking multiple agents:

```typescript theme={null}
raindrop.subscribe(agent1, { userId: "alice", convoId: "alice-session" });
raindrop.subscribe(agent2, { userId: "bob", convoId: "bob-session" });
```

### Extension Configuration

The CLI extension reads config from environment variables and JSON files.

**Precedence:** defaults -> `~/.pi/agent/raindrop.json` -> `.pi/raindrop.json` -> env vars.

| Setting               | Env var                          | Default                      |
| --------------------- | -------------------------------- | ---------------------------- |
| Write key             | `RAINDROP_WRITE_KEY`             | (none)                       |
| API endpoint          | `RAINDROP_API_URL`               | `https://api.raindrop.ai/v1` |
| Debug logging         | `RAINDROP_DEBUG`                 | `false`                      |
| Capture system prompt | `RAINDROP_CAPTURE_SYSTEM_PROMPT` | `false`                      |
| Project slug          | `RAINDROP_PROJECT_ID`            | (none)                       |

### Projects

Route events to a specific [project](/platform/projects) by passing its slug as `projectId` (programmatic) or via `RAINDROP_PROJECT_ID` / the `project_id` config-file key (CLI extension):

```typescript theme={null}
const raindrop = createRaindropPiAgent({
  writeKey: "your-write-key",
  projectId: "support-prod",
});
```

This sets the `X-Raindrop-Project-Id` header on every event. Omit it (or pass `"default"`) to use your org's default **Production** project, which is the existing behavior. Single-project orgs need nothing new.

## Supported Versions

* `@earendil-works/pi-agent-core` >= 0.74.0
* `@earendil-works/pi-coding-agent` >= 0.74.0 (optional, for CLI extension)