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

> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# LangChain Instrumentation

> Instrument LangChain applications with the LangWatch TypeScript SDK to trace chains, RAG flows, and agent evaluation metrics.

> [!TIP]
>
> **Quick setup?** Instead of following these steps manually, [copy a prompt](https://langwatch.ai/docs/skills/directory.md) into your coding agent and it will set this up for you automatically.

LangWatch integrates with Langchain to provide detailed observability into your chains, agents, LLM calls, and tool usage.

## Installation

```bash npm theme={null}
npm i langwatch @langchain/openai @langchain/core
```

```bash pnpm theme={null}
pnpm add langwatch @langchain/openai @langchain/core
```

```bash yarn theme={null}
yarn add langwatch @langchain/openai @langchain/core
```

```bash bun theme={null}
bun add langwatch @langchain/openai @langchain/core
```

## Usage

> [!NOTE]
>
> The LangWatch API key is configured by default via the `LANGWATCH_API_KEY` environment variable.

Use `LangWatchCallbackHandler` to capture Langchain events as spans within your trace.

```typescript theme={null}
import { setupObservability } from "langwatch/observability/node";
import { LangWatchCallbackHandler } from "langwatch/observability/instrumentation/langchain";
import { ChatOpenAI } from "@langchain/openai";
import { HumanMessage } from "@langchain/core/messages";

setupObservability({ serviceName: "<project_name>" });

async function main(message: string): Promise<string> {
  const chatModel = new ChatOpenAI({ model: "gpt-6-luna" }).withConfig({
    callbacks: [new LangWatchCallbackHandler()],
  });

  const result = await chatModel.invoke([new HumanMessage(message)]);
  return result.content as string;
}

console.log(await main("Hey, tell me a joke"));
```

The `LangWatchCallbackHandler` captures Langchain events and converts them into detailed LangWatch spans. Pass the callback handler to your Langchain components via the `callbacks` option in `withConfig()`.

## Check it worked

Run the example. The SDK flushes pending spans when the process exits. Then open your project in LangWatch: a new trace appears in the traces list within a few seconds. Open it to see the LangChain steps and the LLM call.

If no trace appears, check that `LANGWATCH_API_KEY` is set in the environment the process runs in.

## Related

* [Capturing RAG](https://langwatch.ai/docs/integration/typescript/tutorials/capturing-rag.md) - Learn how to capture RAG data from LangChain retrievers and tools
* [Capturing Metadata and Attributes](https://langwatch.ai/docs/integration/typescript/tutorials/capturing-metadata.md) - Add custom metadata and attributes to your traces and spans
* [Capturing Evaluations & Guardrails](https://langwatch.ai/docs/integration/python/tutorials/capturing-evaluations-guardrails.md) - Log evaluations and implement guardrails in your LangChain applications


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.