LangChain (Beta) - Raindrop

Installation

npm install @raindrop-ai/langchain @langchain/core @langchain/openai

pnpm add @raindrop-ai/langchain @langchain/core @langchain/openai

pip install raindrop-langchain langchain-core langchain-openai

Quick Start

import { createRaindropLangChain } from "@raindrop-ai/langchain";
import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage } from "@langchain/core/messages";

const raindrop = createRaindropLangChain({
  writeKey: "your-write-key",
  userId: "user-123",
});

const model = new ChatOpenAI({ model: "gpt-4o" });

const result = await model.invoke(
  [new HumanMessage("What is the capital of France?")],
  { callbacks: [raindrop.handler] },
);

await raindrop.flush();

from raindrop_langchain import create_raindrop_langchain
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

raindrop = create_raindrop_langchain(
    api_key="your-write-key",
    user_id="user-123",
)

model = ChatOpenAI(model="gpt-4o")

result = model.invoke(
    [HumanMessage(content="What is the capital of France?")],
    config={"callbacks": [raindrop.handler]},
)

raindrop.flush()

What Gets Traced

The LangChain integration automatically captures:

LLM calls — model name, input messages, output text, token usage (prompt/completion/total), finish reason
Tool calls — tool name, input arguments, output, duration (via interaction.track_tool() spans)
Chains — chain execution with nested spans
Retrievers — query text and document count
Agent actions — tool selection and execution
Errors — captured with error status on the span
Tags and metadata — LangChain tags and metadata are forwarded to Raindrop event properties
Extended token categories — cached tokens (ai.usage.cached_tokens) and reasoning tokens (ai.usage.thoughts_tokens) when available from the provider (e.g. OpenAI)
Finish reason — captured as ai.finish_reason in event properties (e.g. "stop", "length")

All operations are linked with parent-child relationships, so you can see the full execution tree in the Raindrop dashboard.

Configuration

const raindrop = createRaindropLangChain({
  writeKey: "your-write-key",                // Optional: your Raindrop write key (omit to disable telemetry)
  endpoint: "...",                   // Optional: custom 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)
  eventName: "support_agent",       // Optional: event name for every event (default: "ai_generation")
  debug: false,                      // Optional: enable verbose logging
  traceChains: true,                 // Optional: create spans for chain execution (default: true)
  traceRetrievers: true,             // Optional: create spans for retriever calls (default: true)
  filterLangGraphInternals: true,    // Optional: filter LangGraph noise + dedup (default: true)
});

raindrop = create_raindrop_langchain(
    api_key="your-write-key",                    # Optional: your Raindrop API key (omit to disable telemetry)
    user_id="user-123",                 # Optional: associate events with a user
    convo_id="convo-456",               # Optional: conversation/thread ID
    project_id="support-prod",          # Optional: route events to a specific project (slug)
    event_name="support_agent",          # Optional: event name for every event (default: "ai_generation")
    trace_chains=True,                   # Optional: track chain execution (default: True)
    trace_retrievers=True,               # Optional: track retriever calls (default: True)
    filter_langgraph_internals=True,     # Optional: filter LangGraph noise + dedup (default: True)
    tracing_enabled=True,                # Optional: enable distributed tracing (default: True)
    bypass_otel_for_tools=True,          # Optional: bypass OTEL for tool spans (default: True)
    debug=False,                         # Optional: enable debug logging (default: False)
)

Event name

Every event this integration ships carries an event name (the event field in the dashboard). It defaults to ai_generation. Set eventName (event_name in Python) to label LangChain traffic — e.g. distinguish a support agent from a billing agent:

const raindrop = createRaindropLangChain({
  writeKey: "your-write-key",
  eventName: "support_agent",
});

raindrop = create_raindrop_langchain(
    api_key="your-write-key",
    event_name="support_agent",
)

Projects

Route events to a specific project by passing its slug as projectId (project_id in Python):

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

raindrop = create_raindrop_langchain(
    api_key="your-write-key",
    project_id="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

Available in raindrop-ai>=0.0.56. When one service runs several LangChain agents that should report to different projects, create one RaindropLangchain wrapper per project. Each wrapper owns its own raindrop.Raindrop client, so the two route independently — there is no shared module-level state:

from raindrop_langchain import RaindropLangchain

# One long-lived wrapper per project, created at startup and reused.
rd_support = RaindropLangchain(api_key="your-write-key", project_id="support-prod")
rd_billing = RaindropLangchain(api_key="your-write-key", project_id="billing-prod")

# Pass each wrapper's handler to the corresponding chain/agent.
support_result = support_chain.invoke(
    "How do I reset my password?",
    config={"callbacks": [rd_support.handler]},   # -> support-prod
)
billing_result = billing_chain.invoke(
    "Why was I charged twice?",
    config={"callbacks": [rd_billing.handler]},    # -> billing-prod
)

rd_support.flush()
rd_billing.flush()

Each wrapper owns its configuration and delivery pipeline, so concurrent requests handled by different agents route independently. To share a single client across wrappers (or with the module-level API), construct a raindrop.Raindrop yourself and pass it via client=:

from raindrop import Raindrop

client = Raindrop(api_key="your-write-key", project_id="support-prod")
rd = RaindropLangchain(client=client)

Using with LangGraph

The Raindrop handler works with LangGraph out of the box. It automatically filters LangGraph-internal chain events (graph executor, __start__, __end__, channel nodes) and deduplicates LLM callbacks that LangGraph may fire multiple times. Pass the handler both at graph invocation time and inside your LLM node:

import { createRaindropLangChain } from "@raindrop-ai/langchain";
import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage } from "@langchain/core/messages";
import { StateGraph, MessagesAnnotation, END } from "@langchain/langgraph";
import { ToolNode } from "@langchain/langgraph/prebuilt";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

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

const getWeather = tool(
  async ({ city }) => `The weather in ${city} is 22°C.`,
  { name: "get_weather", description: "Get weather", schema: z.object({ city: z.string() }) },
);

const model = new ChatOpenAI({ model: "gpt-4o-mini" }).bindTools([getWeather]);

const callModel = async (state: typeof MessagesAnnotation.State) => {
  const response = await model.invoke(state.messages, {
    callbacks: [raindrop.handler],
  });
  return { messages: [response] };
};

const graph = new StateGraph(MessagesAnnotation)
  .addNode("agent", callModel)
  .addNode("tools", new ToolNode([getWeather]))
  .addEdge("__start__", "agent")
  .addConditionalEdges("agent", (state) => {
    const last = state.messages[state.messages.length - 1];
    if ("tool_calls" in last && Array.isArray(last.tool_calls) && last.tool_calls.length > 0) return "tools";
    return END;
  })
  .addEdge("tools", "agent")
  .compile();

// Pass callbacks only to the model inside the node — NOT to graph.invoke().
// This ensures clean, deduplicated events without LangGraph internal noise.
const result = await graph.invoke(
  { messages: [new HumanMessage("What's the weather in Paris?")] },
);

await raindrop.shutdown();

from raindrop_langchain import create_raindrop_langchain
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from langchain_core.tools import tool
from langgraph.graph import StateGraph, MessagesState, END
from langgraph.prebuilt import ToolNode

raindrop = create_raindrop_langchain(
    api_key="your-write-key",
    user_id="user-123",
    convo_id="convo-456",
)

@tool
def get_weather(city: str) -> str:
    """Get the weather for a city."""
    return f"The weather in {city} is 22°C."

model = ChatOpenAI(model="gpt-4o-mini").bind_tools([get_weather])

def call_model(state: MessagesState):
    response = model.invoke(
        state["messages"],
        config={"callbacks": [raindrop.handler]},
    )
    return {"messages": [response]}

def should_continue(state: MessagesState):
    last = state["messages"][-1]
    if hasattr(last, "tool_calls") and last.tool_calls:
        return "tools"
    return END

graph = (
    StateGraph(MessagesState)
    .add_node("agent", call_model)
    .add_node("tools", ToolNode([get_weather]))
    .add_edge("__start__", "agent")
    .add_conditional_edges("agent", should_continue)
    .add_edge("tools", "agent")
    .compile()
)

# Pass callbacks only to the model inside the node — NOT to graph.invoke().
result = graph.invoke(
    {"messages": [HumanMessage(content="What's the weather in Paris?")]},
)

raindrop.shutdown()

LangGraph Best Practices

Pass callbacks to the model, not the graph — use callbacks: [raindrop.handler] inside your LLM node function only. Do NOT pass callbacks to graph.invoke() — LangGraph’s internal callback propagation causes duplicate events and noisy chain spans when callbacks are on the graph level.
Create a new handler per request in server environments to avoid state collisions between concurrent graph executions.
LangGraph-internal filtering is on by default — the filterLangGraphInternals option (default: true) skips noisy internal chain events from the graph executor and node wrappers. Set to false if you want full visibility into LangGraph internals.

Using with LangSmith

Raindrop and LangSmith can coexist — both use LangChain’s callback system and receive the same events independently. There is no conflict, but you should be aware of the following:

Both tracers are active simultaneously when LANGSMITH_TRACING=true is set. Each builds its own trace tree from the same callback events. This is safe but means LLM calls are traced twice (once by each system).
To use Raindrop only, disable LangSmith tracing:
LANGSMITH_TRACING=false
To use both, no changes needed. Both handlers receive callbacks and ship data independently. Raindrop traces appear in the Raindrop dashboard; LangSmith traces appear in LangSmith.
Performance: having two tracers adds minimal overhead since both operate asynchronously and don’t block the LLM pipeline.

Usage with Chains

The same handler works with plain LangChain chains:

import { ChatPromptTemplate } from "@langchain/core/prompts";
import { StringOutputParser } from "@langchain/core/output_parsers";

const prompt = ChatPromptTemplate.fromTemplate("Tell me about {topic}");
const chain = prompt.pipe(model).pipe(new StringOutputParser());

const result = await chain.invoke(
  { topic: "quantum computing" },
  { callbacks: [raindrop.handler] },
);

await raindrop.flush();

from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

prompt = ChatPromptTemplate.from_template("Tell me about {topic}")
chain = prompt | model | StrOutputParser()

result = chain.invoke(
    {"topic": "quantum computing"},
    config={"callbacks": [raindrop.handler]},
)

raindrop.flush()

Passing Tags and Metadata

LangChain tags and metadata are forwarded to Raindrop event properties:

const result = await model.invoke(
  [new HumanMessage("Hello")],
  {
    callbacks: [raindrop.handler],
    tags: ["production", "v2"],
    metadata: { experimentId: "exp-123" },
  },
);

Identify Users

Associate events with a user identity after initialization:

raindrop.users.identify({ userId: "user-123", traits: { name: "Alice", plan: "pro" } });

raindrop.identify("user-123", {"name": "Alice", "plan": "pro"})

Track Signals

Send feedback, edits, or custom signals tied to a specific event:

raindrop.signals.track({
  eventId: "evt-abc",
  name: "thumbs_up",
  type: "feedback",
  sentiment: "POSITIVE",
});

raindrop.track_signal(
    event_id="evt-abc",
    name="thumbs_up",
    signal_type="feedback",
    sentiment="POSITIVE",
)

Flushing and Shutdown

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

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

raindrop.flush()     # flush pending data
raindrop.shutdown()  # flush + release resources

​Installation

​Quick Start

​What Gets Traced

​Configuration

​Event name

​Projects

​Multiple projects in one process

​Using with LangGraph

​LangGraph Best Practices

​Using with LangSmith

​Usage with Chains

​Passing Tags and Metadata

​Identify Users

​Track Signals

​Flushing and Shutdown