Pi Agent (Beta) - Raindrop

The @raindrop-ai/pi-agent package automatically instruments Pi (the agent harness and coding agent from pi.dev, source at 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

npm install @raindrop-ai/pi-agent

pnpm add @raindrop-ai/pi-agent

Quick Start — Programmatic

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

pi install npm:@raindrop-ai/pi-agent

Set RAINDROP_WRITE_KEY in your environment. Traces appear automatically. Or configure via ~/.pi/agent/raindrop.json:

{
  "write_key": "your-write-key",
  "capture_system_prompt": true
}

Configuration

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 },
});

Override context per subscription when tracking multiple agents:

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 by passing its slug as projectId (programmatic) or via RAINDROP_PROJECT_ID / the project_id config-file key (CLI extension):

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)

​Installation

​Quick Start — Programmatic

​Quick Start — Pi Coding Agent CLI

​Configuration

​Per-Subscribe Overrides

​Extension Configuration

​Projects

​Supported Versions