> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# LangChain

> Auto-trace LangChain chains, agents, tools, and retrievers

# LangChain

The `@mutagent/langchain` package provides a `MutagentCallbackHandler` that plugs into LangChain's callback system. Every LLM call, chain execution, tool invocation, and retriever query is automatically captured as a trace span with zero code changes to your existing LangChain logic.

## Installation

<CodeGroup>
  ```bash bun theme={null}
  bun add @mutagent/langchain @mutagent/sdk
  ```

  ```bash npm theme={null}
  npm install @mutagent/langchain @mutagent/sdk
  ```

  ```bash yarn theme={null}
  yarn add @mutagent/langchain @mutagent/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @mutagent/langchain @mutagent/sdk
  ```
</CodeGroup>

**Peer dependencies:** `@mutagent/sdk ^0.1.0`, `@langchain/core >=0.1.0`

## Quick Start

<Steps>
  <Step title="Initialize tracing">
    Call `initTracing()` once at application startup. This configures the SDK's span batching and transport layer.

    ```typescript theme={null}
    import { initTracing } from '@mutagent/sdk/tracing';

    initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });
    ```
  </Step>

  <Step title="Create the callback handler">
    Instantiate `MutagentCallbackHandler`. Optionally pass session and user context.

    ```typescript theme={null}
    import { MutagentCallbackHandler } from '@mutagent/langchain';

    const handler = new MutagentCallbackHandler({
      sessionId: 'my-session',  // optional
      userId: 'user-123',       // optional
    });
    ```
  </Step>

  <Step title="Attach to any LangChain component">
    Pass the handler via the `callbacks` option on any LangChain invocation.

    ```typescript theme={null}
    import { ChatOpenAI } from '@langchain/openai';

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

    const result = await llm.invoke('What is observability?', {
      callbacks: [handler],
    });
    // Trace automatically sent to MutagenT
    ```
  </Step>
</Steps>

## Full Example

```typescript theme={null}
import { initTracing } from '@mutagent/sdk/tracing';
import { MutagentCallbackHandler } from '@mutagent/langchain';
import { ChatOpenAI } from '@langchain/openai';
import { PromptTemplate } from '@langchain/core/prompts';
import { RunnableSequence } from '@langchain/core/runnables';

// 1. Initialize SDK tracing (once at app startup)
initTracing({ apiKey: process.env.MUTAGENT_API_KEY! });

// 2. Create the callback handler
const handler = new MutagentCallbackHandler();

// 3. Build your chain as usual
const prompt = PromptTemplate.fromTemplate(
  'Explain {topic} in simple terms.'
);
const llm = new ChatOpenAI({ model: 'gpt-4o' });
const chain = RunnableSequence.from([prompt, llm]);

// 4. Invoke with the callback
const result = await chain.invoke(
  { topic: 'vector databases' },
  { callbacks: [handler] },
);
```

## What Gets Traced

The callback handler captures the following LangChain event types:

| Event                                     | Span Kind   | Data Captured                                        |
| ----------------------------------------- | ----------- | ---------------------------------------------------- |
| `handleLLMStart` / `handleChatModelStart` | `llm.chat`  | Input prompts or messages, model name                |
| `handleLLMEnd`                            | `llm.chat`  | Output text, token usage (prompt, completion, total) |
| `handleChainStart`                        | `chain`     | Chain name, input values                             |
| `handleChainEnd`                          | `chain`     | Output values                                        |
| `handleToolStart`                         | `tool`      | Tool name, input string                              |
| `handleToolEnd`                           | `tool`      | Output string                                        |
| `handleRetrieverStart`                    | `retrieval` | Retriever name, query string                         |
| `handleRetrieverEnd`                      | `retrieval` | Retrieved documents (content + metadata)             |
| Error handlers                            | Any         | Error message and status                             |

Parent-child relationships are preserved: when a chain invokes an LLM which calls a tool, the resulting spans form a nested tree in MutagenT.

## Token Usage Tracking

Token metrics are automatically extracted from `LLMResult.llmOutput.tokenUsage` when available:

* `inputTokens` -- prompt tokens
* `outputTokens` -- completion tokens
* `totalTokens` -- combined total

<Note>
  Token usage availability depends on your LLM provider. OpenAI and Anthropic models report tokens; some open-source models may not.
</Note>

## Handler Options

`MutagentCallbackHandler` accepts optional configuration for session tracking, user attribution, and metadata:

```typescript theme={null}
const handler = new MutagentCallbackHandler({
  sessionId: 'chat-session-123',  // Group traces by session
  userId: 'user-456',             // Attribute traces to a user
  tags: ['production', 'v2'],     // Filter traces by tag
  metadata: { version: '2.0' },   // Custom key-value metadata
});
```

| Option      | Type                      | Description                         |
| ----------- | ------------------------- | ----------------------------------- |
| `sessionId` | `string`                  | Group related traces into a session |
| `userId`    | `string`                  | Attribute traces to a specific user |
| `tags`      | `string[]`                | Tags for filtering in the dashboard |
| `metadata`  | `Record<string, unknown>` | Custom key-value metadata           |

All options are optional. Without options, the handler works with zero configuration — just pass it to any LangChain component.

Configure tracing behavior (batch size, flush interval, etc.) through `initTracing()`:

```typescript theme={null}
initTracing({
  apiKey: process.env.MUTAGENT_API_KEY!,
  batchSize: 20,
  flushIntervalMs: 3000,
});
```

## CLI Shortcut

Generate a complete integration scaffold with the CLI:

```bash theme={null}
mutagent integrate langchain
```

This auto-detects LangChain in your `package.json` (looks for `langchain` or `@langchain/core`) and generates ready-to-use configuration code.

To validate an existing integration setup:

```bash theme={null}
mutagent integrate langchain --verify
```

## Python

Looking for the Python LangChain integration? See the [Python LangChain guide](/integrations/python/langchain).