> ## 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.

# LangGraph

> Build stateful AI applications with LangGraph and Adaline.

# LangGraph

Use the Adaline LangGraph callback handler to send LangGraph executions into Adaline. The integration attaches at the callback layer and works well when your graph nodes already call LangChain-powered models or tools.

## 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](/docs/get-started/integrate-your-ai-agent) 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

```bash theme={null}
pip install adaline-client adaline-langgraph langgraph langchain-openai
```

Install the LangGraph and model-provider packages your application already uses alongside the Adaline integration package.

## Initialize Adaline

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

```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](/docs/instrument/with-adaline-sdks).
</Note>

## Attach the LangGraph callback handler

Create an `AdalineLangGraphCallbackHandler`, then pass it through the graph invocation config.

```python theme={null}
from adaline_langgraph import AdalineLangGraphCallbackHandler

handler = AdalineLangGraphCallbackHandler(
    monitor=monitor,
    session_id="graph-session",
    tags=["langgraph"],
)
```

## Basic example

This example keeps the integration intentionally small: a one-node `StateGraph` that invokes `ChatOpenAI`, with the Adaline handler passed via LangGraph callbacks.

```python theme={null}
import asyncio

from typing_extensions import TypedDict
from langchain_openai import ChatOpenAI
from langgraph.graph import END, START, StateGraph

from adaline_langgraph import AdalineLangGraphCallbackHandler

class State(TypedDict):
    question: str
    answer: str


async def main():
    handler = AdalineLangGraphCallbackHandler(monitor=monitor)
    llm = ChatOpenAI(model="gpt-4o-mini", max_tokens=20)

    def answer_node(state: State) -> State:
        result = llm.invoke(state["question"])
        return {"question": state["question"], "answer": str(result.content)}

    graph = StateGraph(State)
    graph.add_node("answer_node", answer_node)
    graph.add_edge(START, "answer_node")
    graph.add_edge("answer_node", END)
    compiled = graph.compile()

    result = await compiled.ainvoke(
        {"question": "Say hello in one word."},
        config={"callbacks": [handler]},
    )

    await monitor.flush()


asyncio.run(main())
```

## Use an existing parent trace or span

If you already created a trace or span in Adaline, pass it to the handler so LangGraph work is attached underneath it instead of creating a new root trace.

```python theme={null}
parent_trace = monitor.log_trace(
    name="langgraph-run",
    reference_id="langgraph-run-1",
)

handler = AdalineLangGraphCallbackHandler(
    monitor=monitor,
    parent_trace=parent_trace,
)
```

Pass either `parent_trace` or `parent_span`, but not both.

## Helper for merging callbacks

If you already build LangGraph config objects elsewhere, use `with_langgraph_callbacks` to append the Adaline handler without rewriting the rest of the config.

```python theme={null}
from adaline_langgraph import with_langgraph_callbacks

config = with_langgraph_callbacks(existing_config, handler)
compiled.invoke({"question": "Say hello."}, config=config)
```

## What the handler captures

The LangGraph callback handler is designed to capture the callback events emitted during a graph run, including:

* graph and chain-style runs
* nested model calls inside graph nodes
* tool and retriever callbacks emitted through the underlying stack
* tagged root traces created by the handler itself

This page focuses on wiring the handler in. The exact span tree depends on which callbacks your graph execution emits.

## Next steps

<CardGroup cols={2}>
  <Card title="Instrument with the Adaline SDK" icon="code" href="/docs/instrument/with-adaline-sdks">
    Monitor lifecycle, buffering and batching, retries, serverless flushing, and graceful shutdown.
  </Card>

  <Card title="SDK reference" icon="braces" href="/docs/reference/sdk/v2/overview">
    Full class and type reference for the TypeScript and Python SDKs.
  </Card>

  <Card title="All integrations" icon="layout-grid" href="/docs/integrations/introduction">
    Browse every framework and AI-provider integration Adaline supports.
  </Card>

  <Card title="View your logs" icon="line-chart" href="https://app.adaline.ai">
    Open Adaline to see traces and spans land in your project.
  </Card>
</CardGroup>