Deep Agents (Beta)

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.

​

Installation

npm install @raindrop-ai/deep-agents @langchain/core @langchain/anthropic deepagents

​

Quick Start

import { createDeepAgent } from "deepagents";
import { ChatAnthropic } from "@langchain/anthropic";
import { createRaindropDeepAgents } from "@raindrop-ai/deep-agents";

const raindrop = createRaindropDeepAgents({
  writeKey: "your-write-key",
  userId: "user-123",
  convoId: "session-abc",
});

const agent = createDeepAgent({
  model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
  tools: [/* filesystem, shell, etc. */],
});

const result = await agent.invoke(
  { messages: [{ role: "user", content: "Create a hello world file" }] },
  { callbacks: [raindrop.handler] },
);

await raindrop.shutdown();

​

What Gets Traced

• LLM calls — model name, input messages, output text, prompt + completion tokens, finish reason
• Tool calls — tool name (write_todos, read_file, write_file, edit_file, ls, glob, grep, execute, task), input arguments, output, duration, errors as nested TOOL_CALL spans linked to the parent event (via interaction.track_tool())
• Chains — root chain input (the user’s question) and output (the final assistant reply) captured as the canonical event, with aggregated model + token usage merged in from all child LLM calls
• Agent actions — tool selection events captured during the agent loop
• Errors — exception type and message captured for both LLM and tool failures
• Tags & metadata — anything passed via LangChain config={"tags": [...], "metadata": {...}} is forwarded to 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, Anthropic)
• Finish reason — captured as ai.finish_reason in event properties ("stop", "length", "tool_calls", etc.)
• Multi-modal messages — typed-parts content ([{type: "text", text: "..."}, ...]) is extracted cleanly; text parts are concatenated, non-text parts (images, audio) are skipped

​

Configuration

const raindrop = createRaindropDeepAgents({
  writeKey: "your-write-key",         // Optional: omit to disable telemetry
  endpoint: "https://...",            // Optional: custom API endpoint
  userId: "user-123",                 // Optional: associate events with a user
  convoId: "session-abc",             // Optional: conversation/thread ID
  traceChains: true,                  // Optional: create spans for chain execution (default: true)
  debug: false,                       // Optional: enable verbose logging (default: false)
});

​

Tool Calls

import { tool } from "@langchain/core/tools";
import { z } from "zod";

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

const agent = createDeepAgent({
  model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
  tools: [getWeather],
});

​

Tags and Metadata

await agent.invoke(
  { messages: [{ role: "user", content: "Hello" }] },
  {
    callbacks: [raindrop.handler],
    tags: ["production", "v2"],
    metadata: { feature: "onboarding", experimentId: "exp-42" },
  },
);

​

Identify Users

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

​

Track Signals

await agent.invoke(
  { messages: [{ role: "user", content: "..." }] },
  { callbacks: [raindrop.handler] },
);

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

​

Async Usage

// All Deep Agents invocations are already async in TypeScript.
const result = await agent.invoke(
  { messages: [{ role: "user", content: "Hello" }] },
  { callbacks: [raindrop.handler] },
);

​

Debug Mode

const raindrop = createRaindropDeepAgents({
  writeKey: "your-write-key",
  debug: true,
});

​

Flushing and Shutdown

await raindrop.flush();    // optional: send queued events
await raindrop.shutdown(); // flush + release resources (always at process exit)

​

LangGraph Internals

​

Python: wrapt compatibility

​

Known Limitations

• Beta status — API surface may change in minor releases.
• Deep Agents version — Requires deepagents >= 0.5.0.
• Streaming — Token-by-token streaming events are not captured individually; only the final aggregated response per LLM call is tracked.
• Subagent isolation — Each subagent invoked via the task tool fires its own callback chain. Events are correctly grouped by convo_id / convoId, but the parent–child trace relationship across subagents is best-effort.
• OTel context propagation (Python) — The LangChain instrumentor sometimes does not propagate traceloop.association.properties.user_id baggage to every span produced inside a LangGraph callback context. The dashboard still shows the trace under the correct event because the SDK records trace_id on the root event’s properties, but filtering the global Traces page by user_id may not surface every relevant span. Tracked upstream at traceloop/openllmetry#2271.
• Concurrent invocations on a shared handler — A single handler instance keeps one in-flight association / span map at a time. Running multiple agent.invoke(...) calls concurrently with the same handler (e.g. Promise.all([...]) in TS or asyncio.gather(...) in Python) will let later invocations overwrite the earlier one’s interaction. Workaround: instantiate one Raindrop client per concurrent request — sequential invocations on a shared instance are fully supported.
• Long chain inputs/outputs are truncated — Chain-level input and output captured on the root event are truncated to ~8 KB to stay within the SDK’s payload limits. Per-LLM child events still carry full prompts; only the canonical-row summary is shortened.
• Python SDK feature surface — The TypeScript client exposes additional low-level APIs (events.patch, events.finish, events.addAttachments, events.setProperties). The Python SDK uses module-level functions; equivalent capability is exposed as top-level methods (identify(), track_signal()) on the RaindropDeepAgents class.