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

# LangChain / LangGraph

> Instrument LangChain and LangGraph agents with TraceCtrl

## Installation

`tracectrl` is on PyPI. The LangChain instrumentor is not yet published — install it from the source tree.

```bash theme={"dark"}
pip install tracectrl
pip install ./sdk/tracectrl-instrumentation-langchain
```

<Note>
  PyPI publication of `tracectrl-instrumentation-langchain` is pending. Until then, install from a local checkout or via `pip install git+https://github.com/cloudsine/tracectrl.git#subdirectory=sdk/tracectrl-instrumentation-langchain`.
</Note>

## Usage

```python theme={"dark"}
import tracectrl
from tracectrl import tag_agent
from tracectrl.instrumentation.langchain import LangChainInstrumentor

tracectrl.configure(service_name="my-langchain-agent")
LangChainInstrumentor().instrument()

from langchain_openai import ChatOpenAI
from langchain.agents import create_openai_tools_agent, AgentExecutor

llm = ChatOpenAI(model="gpt-4o")
# ... define tools, prompt, agent
agent_executor = AgentExecutor(agent=agent, tools=tools)
tag_agent(agent_executor)

agent_executor.invoke({"input": "Summarize my latest emails"})
```

Call `tag_agent(agent_executor)` (or, for LangGraph, on the compiled graph) so the agent identity propagates onto every span the run produces.

## What Gets Captured

| Span Kind   | Examples                      | Attributes Set                                             |
| ----------- | ----------------------------- | ---------------------------------------------------------- |
| `CHAIN`     | Chain/pipeline runs           | `input.value`, `output.value`                              |
| `LLM`       | `ChatOpenAI`, `ChatAnthropic` | `llm.model_name`, `llm.system`                             |
| `TOOL`      | Tool invocations              | `tool.name`, `tool.description`, `tracectrl.tool.category` |
| `AGENT`     | `AgentExecutor` runs          | `tracectrl.agent.id`, `tracectrl.agent.name`               |
| `RETRIEVER` | Vector store retrievals       | `retrieval.documents`                                      |

## LangGraph Support

LangGraph agents are automatically captured — each node execution appears as a span with parent-child relationships matching the graph structure.

```python theme={"dark"}
from langgraph.graph import StateGraph

graph = StateGraph(MyState)
graph.add_node("researcher", researcher_node)
graph.add_node("writer", writer_node)
compiled = graph.compile()
tag_agent(compiled)
```

## API

### `LangChainInstrumentor()`

<ParamField path="instrument" type="method">
  `instrument(tracer_provider=None, skip_dep_check=False)` — Registers the TraceCtrl span processor and wraps the OpenInference LangChain instrumentor.
</ParamField>

<ParamField path="uninstrument" type="method">
  `uninstrument()` — Shuts down the TraceCtrl processor and unwraps the OpenInference instrumentor.
</ParamField>

<ParamField path="instrumented" type="bool">
  Whether the instrumentor is currently active.
</ParamField>