@raindrop-ai/pi-agent

Automatic observability for Pi Agent with Raindrop. Captures agent runs, LLM generations, tool calls, and token usage.

Two entry points:

• @raindrop-ai/pi-agent — programmatic subscriber for pi-agent-core users
• @raindrop-ai/pi-agent/extension — pi-coding-agent CLI extension (auto-discovered via pi install)

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

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

raindrop.subscribe(agent);
await agent.prompt("Hello!");
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.

Projects

If your org has multiple projects, route events to a specific one by passing its slug as projectId programmatically:

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

For the CLI extension, set the slug via the RAINDROP_PROJECT_ID env var (or the project_id config-file key). Either way this sets the X-Raindrop-Project-Id header on every event. Omit it (or use "default") to use your org's default Production project — the existing behavior. Single-project orgs need nothing new.

Payload size limits

Event input/output are capped at 1,000,000 characters per field (span attributes at 32 KB) and truncated with a ...[truncated by raindrop] marker. The cap is enforced before (or during) serialization, so oversized payloads cost the cap — not the payload — on the host's event loop, and large events land truncated instead of being rejected at the ingest size limit. Hook error logs are rate-limited to one line per failure family per 30s.

Documentation

See the full Pi Agent docs for configuration, per-subscribe overrides, and extension settings.

License

MIT