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

# LangChain

> Build LLM applications with LangChain and Adaline.

# LangChain

Use the Adaline LangChain callback handler to send LangChain runs into Adaline without changing the chain logic itself. The integration attaches at the callback layer and maps model, chain, tool, and retriever events into Adaline traces and spans.

## Prerequisites

Before you start, make sure you have:

* An [Adaline account](https://app.adaline.ai/sign-up?utm_source=adaline.ai).
* A **workspace API key** — create one under **Settings → API keys**.
* Your **project ID** — copy it from **Monitor → Copy Project ID**.

See [Integrate your AI Agent](https://www.adaline.ai/docs/get-started/integrate-your-ai-agent.md) for a full walkthrough.

Set both as environment variables before running the examples on this page:

```bash theme={null}
export ADALINE_API_KEY="your-api-key"
export ADALINE_PROJECT_ID="your-project-id"
```

## Install

> [tab] TypeScript
>
> ```bash theme={null}
> npm install @adaline/client @adaline/langchain @langchain/core @langchain/openai
> ```

> [tab] Python
>
> ```bash theme={null}
> pip install adaline-client adaline-langchain langchain-core langchain-openai
> ```

## Initialize Adaline

Create an Adaline client, then initialize a monitor for the target project.

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Adaline } from "@adaline/client";
>
> const adaline = new Adaline({ apiKey: process.env.ADALINE_API_KEY! });
> const monitor = adaline.initMonitor({ projectId: process.env.ADALINE_PROJECT_ID! });
> ```

> [tab] Python
>
> ```python theme={null}
> import os
>
> from adaline import Adaline
>
> adaline = Adaline(api_key=os.environ["ADALINE_API_KEY"])
> monitor = adaline.init_monitor(project_id=os.environ["ADALINE_PROJECT_ID"])
> ```

> [!NOTE]
>
> For production guidance — buffering, batching, retries, serverless flushing, and graceful shutdown — see [Instrument with the Adaline SDK](https://www.adaline.ai/docs/instrument/with-adaline-sdks.md).

## Attach the LangChain callback handler

Add the Adaline callback handler to the LangChain call path. Your application code can keep using the same chain, model, tool, and retriever APIs.

> [tab] TypeScript
>
> ```typescript theme={null}
> import { AdalineLangChainCallbackHandler } from "@adaline/langchain";
>
> const handler = new AdalineLangChainCallbackHandler({ monitor });
> ```

> [tab] Python
>
> ```python theme={null}
> from adaline_langchain import AdalineLangChainCallbackHandler
>
> handler = AdalineLangChainCallbackHandler(monitor=monitor)
> ```

## Basic example

This example keeps the integration intentionally small: one `ChatOpenAI` call with the Adaline callback handler attached.

> [tab] TypeScript
>
> ```typescript theme={null}
> import { ChatOpenAI } from "@langchain/openai";
> import { AdalineLangChainCallbackHandler } from "@adaline/langchain";
>
> const handler = new AdalineLangChainCallbackHandler({ monitor });
>
> const model = new ChatOpenAI({
>   modelName: "gpt-4o-mini",
>   maxTokens: 20,
>   callbacks: [handler],
> });
>
> const result = await model.invoke("Say hello in one word.");
> await monitor.flush();
> ```

> [tab] Python
>
> ```python theme={null}
> import asyncio
>
> from langchain_openai import ChatOpenAI
> from adaline_langchain import AdalineLangChainCallbackHandler
>
> async def main():
>     handler = AdalineLangChainCallbackHandler(monitor=monitor)
>     llm = ChatOpenAI(model="gpt-4o-mini", max_tokens=20, callbacks=[handler])
>     result = await llm.ainvoke("Say hello in one word.")
>     await monitor.flush()
>
>
> asyncio.run(main())
> ```

## Use an existing parent trace or span

If you already created a trace or span in Adaline, you can attach LangChain work underneath it instead of letting the handler create a new root trace.

> [tab] TypeScript
>
> ```typescript theme={null}
> const parentTrace = monitor.logTrace({
>   name: "langchain-run",
>   referenceId: "langchain-run-1",
> });
>
> const handler = new AdalineLangChainCallbackHandler({
>   monitor,
>   parentTrace,
> });
> ```

> [tab] Python
>
> ```python theme={null}
> parent_trace = monitor.log_trace(
>     name="langchain-run",
>     reference_id="langchain-run-1",
> )
>
> handler = AdalineLangChainCallbackHandler(
>     monitor=monitor,
>     parent_trace=parent_trace,
> )
> ```

Pass either `parentTrace` / `parent_trace` or `parentSpan` / `parent_span`, but not both.

## Global handler

LangChain can also use a global Adaline handler instead of passing callbacks manually on every invocation.

> [tab] TypeScript
>
> ```typescript theme={null}
> import {
>   AdalineLangChainCallbackHandler,
>   setGlobalHandler,
> } from "@adaline/langchain";
>
> setGlobalHandler(new AdalineLangChainCallbackHandler({ monitor }));
> ```

> [tab] Python
>
> ```python theme={null}
> from adaline_langchain import AdalineLangChainCallbackHandler, set_global_handler
>
> set_global_handler(AdalineLangChainCallbackHandler(monitor=monitor))
> ```

Use `clearGlobalHandler()` or `clear_global_handler()` to remove it.

## What the handler captures

The callback handler is designed to map LangChain run trees into Adaline observations, including:

* chain runs
* chat model and LLM runs
* tool runs
* retriever runs
* nested child runs under a shared parent run

This page focuses on how to wire the handler in. The exact span shape depends on which LangChain components your application uses and which callbacks they emit.

## Next steps

> [card] [Instrument with the Adaline SDK](https://www.adaline.ai/docs/instrument/with-adaline-sdks.md)
>
> Monitor lifecycle, buffering and batching, retries, serverless flushing, and graceful shutdown.

> [card] [SDK reference](https://www.adaline.ai/docs/reference/sdk/v2/overview)
>
> Full class and type reference for the TypeScript and Python SDKs.

> [card] [All integrations](https://www.adaline.ai/docs/integrations/introduction.md)
>
> Browse every framework and AI-provider integration Adaline supports.

> [card] [View your logs](https://app.adaline.ai)
>
> Open Adaline to see traces and spans land in your project.


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