> ## 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](/docs/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)

## Tool catalog capture (`ai.prompt.tools`)

Each model span records the agent's `context.tools` as `ai.prompt.tools`: one JSON document per tool with `name`, `description` and the full TypeBox `parameters` schema as `inputSchema`. Unlike the tools preview inside `ai.prompt`, this list is not subject to the text budget, so schemas survive intact. Absent when the agent has no tool list. `tools` is accepted on `createRaindropPiAgent(...)` and per subscription via `subscribe(agent, { tools })` (the subscription value wins); it replaces the inferred list and `tools: []` records an empty catalog. See [Tool catalog capture](/docs/sdk/tool-catalog) for the attribute format, the absent / `[]` semantics and the override shapes accepted.

## Application Git identity

Set `appGit` on `createRaindropPiAgent` to provide `commitSha`, `commitDirty`, and optional `branch`,
or pass `false` to opt out. Pi can observe coding workspaces remotely, so local discovery requires a
`sourceDirectory` that explicitly identifies the AUT and never defaults to the edited workspace. See
the [TypeScript Git reference](/docs/sdk/typescript#application-git-provenance).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.