@raindrop-ai/langchain 0.0.9 → 0.1.0

package/README.md

@@ -49,7 +49,7 @@ await raindrop.flush();
 | `projectId` | `string` | - | Route events to a specific project (slug); omit for the default **Production** project |
 | `eventName` | `string` | `ai_generation` | Event name applied to every event (the `event` field in the dashboard) |
 | `debug` | `boolean` | `false` | Enable verbose logging |
-| `traceChains` | `boolean` | `true` | Create spans for chain execution |
+| `traceChains` | `boolean` | `false` | Create spans for chain/runnable execution. Off by default because LangGraph agents emit many structural "chain" spans that bury the LLM and tool spans. |
 | `traceRetrievers` | `boolean` | `true` | Create spans for retriever calls |
 | `filterLangGraphInternals` | `boolean` | `true` | Filter LangGraph-internal chain events and deduplicate LLM callbacks |
 | `maxTextFieldChars` | `number` | `1000000` | Per-field cap for event input/output and serialized span payloads, enforced before/during serialization (truncated values end with `...[truncated by raindrop]`; a stricter `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is honored) |
@@ -67,17 +67,58 @@ const raindrop = createRaindropLangChain({
 
 This sets the `X-Raindrop-Project-Id` header on every event. Omit it (or pass `"default"`) to use your org's default **Production** project — the existing behavior. Single-project orgs need nothing new.
 
-## LangGraph Support
+## Agents (LangGraph / ReAct)
 
-Works with LangGraph out of the box. The handler automatically:
+For a prebuilt agent (`createReactAgent`) or any LangGraph graph, pass the handler
+**once** to the top-level `invoke` call. LangChain propagates the callback down to
+every LLM step and tool call in the run, and the handler threads them onto a single
+Raindrop event (with a span tree) via each callback's `runId`/`parentRunId`.
+
+```typescript
+import { createRaindropLangChain } from "@raindrop-ai/langchain";
+import { ChatOpenAI } from "@langchain/openai";
+import { tool } from "@langchain/core/tools";
+import { createReactAgent } from "@langchain/langgraph/prebuilt";
+import { z } from "zod";
+
+const raindrop = createRaindropLangChain({
+  writeKey: "your-write-key",
+  userId: "user-123",
+  eventName: "support-agent",
+});
+
+const getWeather = tool(async ({ city }) => `It is sunny and 72F in ${city}.`, {
+  name: "get_weather",
+  description: "Get the current weather for a city.",
+  schema: z.object({ city: z.string() }),
+});
+
+const agent = createReactAgent({
+  llm: new ChatOpenAI({ model: "gpt-4o-mini" }),
+  tools: [getWeather],
+});
+
+// One handler on the top-level invoke captures the whole agent run:
+// LLM steps + tool calls, all on one event.
+await agent.invoke(
+  { messages: [{ role: "user", content: "What's the weather in SF?" }] },
+  { callbacks: [raindrop.handler] },
+);
+
+await raindrop.flush(); // await before the process/lambda exits
+```
+
+See `examples/langchain-agent-basic/` for a full runnable example.
+
+The handler works with LangGraph out of the box and automatically:
 - Filters LangGraph-internal chain events (graph executor, `__start__`, `__end__`, channel nodes)
 - Deduplicates LLM callbacks that LangGraph fires multiple times with the same `runId`
 
-Pass the handler both at `graph.invoke()` and inside your LLM node. See `examples/langchain-langgraph-basic/` for a full example.
-
 **Best practices:**
-- Pass callbacks to the **model inside your node**, not to `graph.invoke()` — this avoids duplicate events from LangGraph's internal callback propagation
-- Create a new handler instance per request in server environments
+- **Prebuilt agents / graphs**: attach the handler to the top-level `invoke(...)` (as above). This is the one place that reliably captures the full run.
+- **Hand-built graphs with custom callback wiring**: attach the handler to the **model inside your node** rather than duplicating it at each layer, to avoid double events from manual callback propagation.
+- Create a new handler instance per request in server environments.
+- Always `await raindrop.flush()` (or `shutdown()`) before exit — in short scripts and serverless the process can freeze before the batched spans ship.
 
 ## LangSmith Coexistence
 

package/dist/index.d.mts

@@ -435,6 +435,12 @@ interface RaindropCallbackHandlerOptions {
     traceShipper: TraceShipper;
     userId?: string;
     convoId?: string;
+    /**
+     * Emit a span for every chain / runnable event. For LangGraph agents this
+     * produces many structural "chain" spans (per-node runnable wrappers) that
+     * bury the meaningful LLM and tool spans, so it defaults to `false`. The
+     * event is still finalized correctly when a chain is the root run.
+     */
     traceChains?: boolean;
     traceRetrievers?: boolean;
     /**
@@ -510,6 +516,11 @@ interface LangChainOptions {
      * generic default. Defaults to `"ai_generation"`.
      */
     eventName?: string;
+    /**
+     * Emit a span for every chain / runnable event. LangGraph agents produce many
+     * structural "chain" spans (per-node runnable wrappers) that bury the LLM and
+     * tool spans, so this defaults to `false`. Event threading is unaffected.
+     */
     traceChains?: boolean;
     traceRetrievers?: boolean;
     /**

package/dist/index.d.ts

@@ -435,6 +435,12 @@ interface RaindropCallbackHandlerOptions {
     traceShipper: TraceShipper;
     userId?: string;
     convoId?: string;
+    /**
+     * Emit a span for every chain / runnable event. For LangGraph agents this
+     * produces many structural "chain" spans (per-node runnable wrappers) that
+     * bury the meaningful LLM and tool spans, so it defaults to `false`. The
+     * event is still finalized correctly when a chain is the root run.
+     */
     traceChains?: boolean;
     traceRetrievers?: boolean;
     /**
@@ -510,6 +516,11 @@ interface LangChainOptions {
      * generic default. Defaults to `"ai_generation"`.
      */
     eventName?: string;
+    /**
+     * Emit a span for every chain / runnable event. LangGraph agents produce many
+     * structural "chain" spans (per-node runnable wrappers) that bury the LLM and
+     * tool spans, so this defaults to `false`. Event threading is unaffected.
+     */
     traceChains?: boolean;
     traceRetrievers?: boolean;
     /**

package/dist/index.js

@@ -1323,6 +1323,7 @@ function boundedStringify(value, limit) {
 }
 
 // src/callback-handler.ts
+var MESSAGE_CONTENT_CAP = 4096;
 var LANGGRAPH_INTERNAL_NAMES = /* @__PURE__ */ new Set([
   "LangGraph",
   "__start__",
@@ -1342,7 +1343,7 @@ var RaindropCallbackHandler = class extends import_base.BaseCallbackHandler {
     this.traceShipper = opts.traceShipper;
     this.userId = opts.userId;
     this.convoId = opts.convoId;
-    this.traceChains = (_a = opts.traceChains) != null ? _a : true;
+    this.traceChains = (_a = opts.traceChains) != null ? _a : false;
     this.traceRetrievers = (_b = opts.traceRetrievers) != null ? _b : true;
     this.filterLangGraphInternals = (_c = opts.filterLangGraphInternals) != null ? _c : true;
   }
@@ -1402,9 +1403,20 @@ var RaindropCallbackHandler = class extends import_base.BaseCallbackHandler {
         name: "llm",
         parent: this.getParent(parentRunId),
         eventId,
+        // `ai.generateText` classifies the span as an LLM generation at ingest
+        // (a bare `llm`/`chat` operationId maps to INTERNAL and is skipped by
+        // the rich-interaction extractor). `ai.prompt.messages` carries the
+        // per-step trajectory so the Convo view can weave in tool calls
+        // inline, matching the shape the ai-sdk / strands SDKs emit.
         attributes: [
           attrString("ai.model.provider", modelId),
-          attrString("ai.operationId", "llm")
+          attrString("ai.operationId", "ai.generateText"),
+          attrString(
+            "ai.prompt.messages",
+            boundedStringify([
+              { role: "user", content: capText2(prompts.join("\n"), MESSAGE_CONTENT_CAP) }
+            ])
+          )
         ]
       });
       this.spans.set(runId, span);
@@ -1424,17 +1436,21 @@ var RaindropCallbackHandler = class extends import_base.BaseCallbackHandler {
       if (this.filterLangGraphInternals && this.spans.has(runId)) return;
       const eventId = this.getEventId(runId, parentRunId);
       const modelId = getName(llm, runName);
+      const allMessages = messages.flat();
       const span = this.traceShipper.startSpan({
         name: "llm",
         parent: this.getParent(parentRunId),
         eventId,
+        // See handleLLMStart: `ai.generateText` + `ai.prompt.messages` let the
+        // rich-interaction extractor render this step (and any tool calls
+        // between it and the next step) inline in the Convo view.
         attributes: [
           attrString("ai.model.provider", modelId),
-          attrString("ai.operationId", "chat")
+          attrString("ai.operationId", "ai.generateText"),
+          attrString("ai.prompt.messages", serializeChatMessages(allMessages))
         ]
       });
       this.spans.set(runId, span);
-      const allMessages = messages.flat();
       const userMessages = allMessages.filter((m) => {
         var _a, _b;
         const role = (_b = (_a = m._getType) == null ? void 0 : _a.call(m)) != null ? _b : "unknown";
@@ -1463,6 +1479,10 @@ var RaindropCallbackHandler = class extends import_base.BaseCallbackHandler {
       this.traceShipper.endSpan(span, {
         attributes: [
           attrString("ai.response.model", model),
+          // The assistant completion for this step; paired with
+          // `ai.prompt.messages` this is what the Convo view renders as the
+          // assistant turn (empty on tool-only steps, so no blank bubble).
+          attrString("ai.response.text", capText2(outputText, MESSAGE_CONTENT_CAP)),
           attrInt("ai.usage.prompt_tokens", promptTokens),
           attrInt("ai.usage.completion_tokens", completionTokens)
         ]
@@ -1547,12 +1567,13 @@ var RaindropCallbackHandler = class extends import_base.BaseCallbackHandler {
       const eventId = this.getEventId(runId, parentRunId);
       const toolName = getName(tool, runName);
       const span = this.traceShipper.startSpan({
-        name: "tool",
+        name: "ai.toolCall",
         parent: this.getParent(parentRunId),
         eventId,
+        operationId: "ai.toolCall",
         attributes: [
-          attrString("tool.name", toolName),
-          attrString("tool.input", truncate(input, 4096))
+          attrString("ai.toolCall.name", toolName),
+          attrString("ai.toolCall.args", truncate(input, 4096))
         ]
       });
       this.spans.set(runId, span);
@@ -1566,7 +1587,7 @@ var RaindropCallbackHandler = class extends import_base.BaseCallbackHandler {
       if (span) {
         const outputStr = typeof output === "string" ? output : safeStringify(output, 4096);
         this.traceShipper.endSpan(span, {
-          attributes: [attrString("tool.output", truncate(outputStr, 4096))]
+          attributes: [attrString("ai.toolCall.result", truncate(outputStr, 4096))]
         });
       }
       await this.finalizeEventIfRoot(runId);
@@ -1599,6 +1620,9 @@ var RaindropCallbackHandler = class extends import_base.BaseCallbackHandler {
         name: "retriever",
         parent: this.getParent(parentRunId),
         eventId,
+        // Ingest drops spans without an `ai.operationId` (or traceloop/gen_ai)
+        // attribute; stamp one so retriever spans are persisted.
+        operationId: "retriever",
         attributes: [
           attrString("retriever.name", retrieverName),
           attrString("retriever.query", truncate(query, 2048))
@@ -1646,6 +1670,9 @@ var RaindropCallbackHandler = class extends import_base.BaseCallbackHandler {
         name: "agent_action",
         parent: this.getParent(parentRunId),
         eventId,
+        // Ingest drops spans without an `ai.operationId` (or traceloop/gen_ai)
+        // attribute; stamp one so agent_action spans are persisted.
+        operationId: "agent_action",
         attributes: [
           attrString("agent.tool", action.tool),
           attrString("agent.tool_input", truncate(
@@ -1700,6 +1727,30 @@ function truncate(str, maxLen) {
   if (str.length <= maxLen) return str;
   return str.slice(0, maxLen - 3) + "...";
 }
+function messageRole(message) {
+  var _a;
+  switch ((_a = message._getType) == null ? void 0 : _a.call(message)) {
+    case "human":
+      return "user";
+    case "ai":
+      return "assistant";
+    case "system":
+      return "system";
+    case "tool":
+    case "function":
+      return "tool";
+    default:
+      return "user";
+  }
+}
+function serializeChatMessages(messages) {
+  if (messages.length === 0) return void 0;
+  const shaped = messages.map((message) => ({
+    role: messageRole(message),
+    content: typeof message.content === "string" ? capText2(message.content, MESSAGE_CONTENT_CAP) : message.content
+  }));
+  return boundedStringify(shaped);
+}
 function extractLLMMetadata(output) {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
   const gen = (_b = (_a = output.generations) == null ? void 0 : _a[0]) == null ? void 0 : _b[0];
@@ -1720,7 +1771,7 @@ function extractLLMMetadata(output) {
 // package.json
 var package_default = {
   name: "@raindrop-ai/langchain",
-  version: "0.0.9",
+  version: "0.1.0",
   description: "Raindrop integration for LangChain",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/dist/index.mjs

@@ -1296,6 +1296,7 @@ function boundedStringify(value, limit) {
 }
 
 // src/callback-handler.ts
+var MESSAGE_CONTENT_CAP = 4096;
 var LANGGRAPH_INTERNAL_NAMES = /* @__PURE__ */ new Set([
   "LangGraph",
   "__start__",
@@ -1315,7 +1316,7 @@ var RaindropCallbackHandler = class extends BaseCallbackHandler {
     this.traceShipper = opts.traceShipper;
     this.userId = opts.userId;
     this.convoId = opts.convoId;
-    this.traceChains = (_a = opts.traceChains) != null ? _a : true;
+    this.traceChains = (_a = opts.traceChains) != null ? _a : false;
     this.traceRetrievers = (_b = opts.traceRetrievers) != null ? _b : true;
     this.filterLangGraphInternals = (_c = opts.filterLangGraphInternals) != null ? _c : true;
   }
@@ -1375,9 +1376,20 @@ var RaindropCallbackHandler = class extends BaseCallbackHandler {
         name: "llm",
         parent: this.getParent(parentRunId),
         eventId,
+        // `ai.generateText` classifies the span as an LLM generation at ingest
+        // (a bare `llm`/`chat` operationId maps to INTERNAL and is skipped by
+        // the rich-interaction extractor). `ai.prompt.messages` carries the
+        // per-step trajectory so the Convo view can weave in tool calls
+        // inline, matching the shape the ai-sdk / strands SDKs emit.
         attributes: [
           attrString("ai.model.provider", modelId),
-          attrString("ai.operationId", "llm")
+          attrString("ai.operationId", "ai.generateText"),
+          attrString(
+            "ai.prompt.messages",
+            boundedStringify([
+              { role: "user", content: capText2(prompts.join("\n"), MESSAGE_CONTENT_CAP) }
+            ])
+          )
         ]
       });
       this.spans.set(runId, span);
@@ -1397,17 +1409,21 @@ var RaindropCallbackHandler = class extends BaseCallbackHandler {
       if (this.filterLangGraphInternals && this.spans.has(runId)) return;
       const eventId = this.getEventId(runId, parentRunId);
       const modelId = getName(llm, runName);
+      const allMessages = messages.flat();
       const span = this.traceShipper.startSpan({
         name: "llm",
         parent: this.getParent(parentRunId),
         eventId,
+        // See handleLLMStart: `ai.generateText` + `ai.prompt.messages` let the
+        // rich-interaction extractor render this step (and any tool calls
+        // between it and the next step) inline in the Convo view.
         attributes: [
           attrString("ai.model.provider", modelId),
-          attrString("ai.operationId", "chat")
+          attrString("ai.operationId", "ai.generateText"),
+          attrString("ai.prompt.messages", serializeChatMessages(allMessages))
         ]
       });
       this.spans.set(runId, span);
-      const allMessages = messages.flat();
       const userMessages = allMessages.filter((m) => {
         var _a, _b;
         const role = (_b = (_a = m._getType) == null ? void 0 : _a.call(m)) != null ? _b : "unknown";
@@ -1436,6 +1452,10 @@ var RaindropCallbackHandler = class extends BaseCallbackHandler {
       this.traceShipper.endSpan(span, {
         attributes: [
           attrString("ai.response.model", model),
+          // The assistant completion for this step; paired with
+          // `ai.prompt.messages` this is what the Convo view renders as the
+          // assistant turn (empty on tool-only steps, so no blank bubble).
+          attrString("ai.response.text", capText2(outputText, MESSAGE_CONTENT_CAP)),
           attrInt("ai.usage.prompt_tokens", promptTokens),
           attrInt("ai.usage.completion_tokens", completionTokens)
         ]
@@ -1520,12 +1540,13 @@ var RaindropCallbackHandler = class extends BaseCallbackHandler {
       const eventId = this.getEventId(runId, parentRunId);
       const toolName = getName(tool, runName);
       const span = this.traceShipper.startSpan({
-        name: "tool",
+        name: "ai.toolCall",
         parent: this.getParent(parentRunId),
         eventId,
+        operationId: "ai.toolCall",
         attributes: [
-          attrString("tool.name", toolName),
-          attrString("tool.input", truncate(input, 4096))
+          attrString("ai.toolCall.name", toolName),
+          attrString("ai.toolCall.args", truncate(input, 4096))
         ]
       });
       this.spans.set(runId, span);
@@ -1539,7 +1560,7 @@ var RaindropCallbackHandler = class extends BaseCallbackHandler {
       if (span) {
         const outputStr = typeof output === "string" ? output : safeStringify(output, 4096);
         this.traceShipper.endSpan(span, {
-          attributes: [attrString("tool.output", truncate(outputStr, 4096))]
+          attributes: [attrString("ai.toolCall.result", truncate(outputStr, 4096))]
         });
       }
       await this.finalizeEventIfRoot(runId);
@@ -1572,6 +1593,9 @@ var RaindropCallbackHandler = class extends BaseCallbackHandler {
         name: "retriever",
         parent: this.getParent(parentRunId),
         eventId,
+        // Ingest drops spans without an `ai.operationId` (or traceloop/gen_ai)
+        // attribute; stamp one so retriever spans are persisted.
+        operationId: "retriever",
         attributes: [
           attrString("retriever.name", retrieverName),
           attrString("retriever.query", truncate(query, 2048))
@@ -1619,6 +1643,9 @@ var RaindropCallbackHandler = class extends BaseCallbackHandler {
         name: "agent_action",
         parent: this.getParent(parentRunId),
         eventId,
+        // Ingest drops spans without an `ai.operationId` (or traceloop/gen_ai)
+        // attribute; stamp one so agent_action spans are persisted.
+        operationId: "agent_action",
         attributes: [
           attrString("agent.tool", action.tool),
           attrString("agent.tool_input", truncate(
@@ -1673,6 +1700,30 @@ function truncate(str, maxLen) {
   if (str.length <= maxLen) return str;
   return str.slice(0, maxLen - 3) + "...";
 }
+function messageRole(message) {
+  var _a;
+  switch ((_a = message._getType) == null ? void 0 : _a.call(message)) {
+    case "human":
+      return "user";
+    case "ai":
+      return "assistant";
+    case "system":
+      return "system";
+    case "tool":
+    case "function":
+      return "tool";
+    default:
+      return "user";
+  }
+}
+function serializeChatMessages(messages) {
+  if (messages.length === 0) return void 0;
+  const shaped = messages.map((message) => ({
+    role: messageRole(message),
+    content: typeof message.content === "string" ? capText2(message.content, MESSAGE_CONTENT_CAP) : message.content
+  }));
+  return boundedStringify(shaped);
+}
 function extractLLMMetadata(output) {
   var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m;
   const gen = (_b = (_a = output.generations) == null ? void 0 : _a[0]) == null ? void 0 : _b[0];
@@ -1693,7 +1744,7 @@ function extractLLMMetadata(output) {
 // package.json
 var package_default = {
   name: "@raindrop-ai/langchain",
-  version: "0.0.9",
+  version: "0.1.0",
   description: "Raindrop integration for LangChain",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raindrop-ai/langchain",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "description": "Raindrop integration for LangChain",
   "main": "dist/index.js",
   "module": "dist/index.mjs",