Skip to main content
The @raindrop-ai/pi-agent package automatically instruments Pi Agent 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

​
Quick Start — Programmatic

import { Agent } from "@mariozechner/pi-agent-core";
import { getModel } from "@mariozechner/pi-ai";
import { createRaindropPiAgent } from "@raindrop-ai/pi-agent";

const raindrop = createRaindropPiAgent({
  writeKey: "rk_...",
  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": "rk_...",
  "capture_system_prompt": true
}

​
Configuration

const raindrop = createRaindropPiAgent({
  writeKey: "rk_...",                        // Optional — omit to disable
  userId: "user-123",
  convoId: "session-abc",
  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: 
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.
SettingEnv varDefault
Write keyRAINDROP_WRITE_KEY—
API endpointRAINDROP_API_URLhttps://api.raindrop.ai/v1
Debug loggingRAINDROP_DEBUGfalse
Capture system promptRAINDROP_CAPTURE_SYSTEM_PROMPTfalse

​
Supported Versions

  • @mariozechner/pi-agent-core >= 0.60.0
  • @mariozechner/pi-coding-agent >= 0.65.2 (optional, for CLI extension)