OpenRouter Agent SDK (Beta)

Raindrop automatically instruments the OpenRouter Agent SDK (@openrouter/agent) to capture events and traces for model calls, tool execution, and multi-turn agent loops.

Installation

npm install @raindrop-ai/openrouter-agent @openrouter/agent

pnpm add @raindrop-ai/openrouter-agent @openrouter/agent

yarn add @raindrop-ai/openrouter-agent @openrouter/agent

bun add @raindrop-ai/openrouter-agent @openrouter/agent

Quick Start

import { OpenRouter, tool } from "@openrouter/agent";
import { z } from "zod";
import { createRaindropOpenRouterAgent } from "@raindrop-ai/openrouter-agent";

const raindrop = createRaindropOpenRouterAgent({
  writeKey: "your-write-key",
  userId: "user-123",
  convoId: "convo-456",
});

const openrouter = raindrop.wrap(
  new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY }),
);

const getWeather = tool({
  name: "get_weather",
  description: "Get the weather for a city.",
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ forecast: z.string() }),
  execute: async ({ city }) => ({ forecast: `Sunny in ${city}` }),
});

const result = openrouter.callModel({
  model: "openai/gpt-4o-mini",
  input: "Use get_weather for San Francisco, then answer briefly.",
  tools: [getWeather] as const,
});

console.log(await result.getText());

await raindrop.shutdown();

Telemetry is finalized when the ModelResult is consumed with getText(), getResponse(), or a stream method.

Standalone `callModel`

If you import OpenRouter’s standalone callModel helper, wrap that function once and call the wrapped version:

import { OpenRouter, callModel } from "@openrouter/agent";
import { createRaindropOpenRouterAgent } from "@raindrop-ai/openrouter-agent";

const raindrop = createRaindropOpenRouterAgent({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  userId: "user-123",
});

const trackedCallModel = raindrop.wrapCallModel(callModel);
const openrouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });

const result = trackedCallModel(openrouter, {
  model: "openai/gpt-4o-mini",
  input: "Hello from OpenRouter",
});

console.log(await result.getText());

await raindrop.shutdown();

What Gets Traced

Agent calls - input, output, model, response ID, response status, and token usage when OpenRouter returns it
Tool calls - client tool executions captured as ai.toolCall trace spans linked to the root event
Conversation grouping - pass convoId to group related agent calls
Errors - failed OpenRouter calls finalize an error event before re-throwing to your application
Signals and users - use the included signals.track and users.identify APIs alongside automatic events

Tool spans are linked to the root event so you can inspect the full execution path in the Trace tab.

Configuration

const raindrop = createRaindropOpenRouterAgent({
  writeKey: "your-write-key",       // Optional: omit to disable telemetry
  endpoint: "...",                  // Optional: custom Raindrop API endpoint
  userId: "user-123",               // Optional: associate events with a user
  convoId: "convo-456",             // Optional: conversation/thread ID
  projectId: "support-prod",        // Optional: route events to a specific project (slug)
  debug: false,                     // Optional: enable verbose logging
});

Projects

Route events to a specific project by passing its slug as projectId:

const raindrop = createRaindropOpenRouterAgent({
  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.

Multiple projects in one process

To report to different projects from one process, create one createRaindropOpenRouterAgent(...) client per project and wrap a distinct OpenRouter client object with each. Each wrapped client ships under its own writeKey/X-Raindrop-Project-Id:

const rdSupport = createRaindropOpenRouterAgent({ writeKey: KEY, projectId: "support-prod" });
const rdBilling = createRaindropOpenRouterAgent({ writeKey: KEY, projectId: "billing-prod" });

const support = rdSupport.wrap(new OpenRouter({ apiKey: OR_KEY })); // -> support-prod
const billing = rdBilling.wrap(new OpenRouter({ apiKey: OR_KEY })); // -> billing-prod

Wrap markers are client-agnostic: re-wrapping the same OpenRouter client object with a second Raindrop client is a silent no-op — the first wrapper keeps it and the second client’s project is never applied. Wrap a distinct OpenRouter client object per project.

Identify Users

Associate traits with a user for filtering and trajectories:

await raindrop.users.identify({
  userId: "user-123",
  traits: {
    plan: "pro",
    company: "Acme",
  },
});

Track Signals

Attach feedback, labels, or other signals to the most recently captured event:

if (raindrop.lastEventId) {
  await raindrop.signals.track({
    eventId: raindrop.lastEventId,
    name: "thumbs_up",
    type: "feedback",
    sentiment: "POSITIVE",
  });
}

Flushing and Shutdown

Always call flush() or shutdown() before your process exits to ensure all telemetry is shipped:

await raindrop.flush();     // flush pending data
await raindrop.shutdown();  // flush + release resources

Known Limitations

Creating a ModelResult without consuming it does not ship an event.
Client tool spans wrap the local tool execution function, so their timing reflects local tool runtime.
Server-executed OpenRouter tools are represented from response items when OpenRouter returns them after the provider response completes. Client function tools have the richest live trace data.

​Installation

​Quick Start

​Standalone callModel

​What Gets Traced

​Configuration

​Projects

​Multiple projects in one process

​Identify Users

​Track Signals

​Flushing and Shutdown

​Known Limitations

Installation

Quick Start

Standalone `callModel`

What Gets Traced

Configuration

Projects

Multiple projects in one process

Identify Users

Track Signals

Flushing and Shutdown

Known Limitations