references/langgraph.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
LangGraph AI Observability installation
Canonical URL: https://posthog.com/docs/ai-observability/installation/langgraph
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
Let AI instrument your LLM calls for you
Skip the manual setup — run this in your project and the wizard installs the SDK and wires up AI Observability for you.
npx @posthog/wizard ai-observability
PostHog Wizard hedgehog
Let AI instrument your LLM calls for you
-
1
Install dependencies
Required
Full working examples
See the complete Node.js and Python examples on GitHub.
Install the PostHog SDK and LangGraph with OpenAI.
Python
pip install posthog langgraph langchain-core langchain-openaiNode
npm install posthog-node @posthog/ai @langchain/langgraph @langchain/openai @langchain/core zod -
2
Configure PostHog
Required
Create a PostHog client once, then build a callback handler for each request or conversation.
distinct_idties each call to a user, and$ai_session_idgroups calls in one conversation.Python
from posthog import Posthog from posthog.ai.langchain import CallbackHandler posthog = Posthog("<ph_project_token>", host="https://us.i.posthog.com") def create_handler(user_id: str, session_id: str) -> CallbackHandler: return CallbackHandler( client=posthog, distinct_id=user_id, properties={"$ai_session_id": session_id}, )Node
import { PostHog } from 'posthog-node' import { LangChainCallbackHandler } from '@posthog/ai/langchain' const posthog = new PostHog('<ph_project_token>', { host: 'https://us.i.posthog.com' }) function createHandler(userId: string, sessionId: string): LangChainCallbackHandler { return new LangChainCallbackHandler({ client: posthog, distinctId: userId, properties: { $ai_session_id: sessionId }, }) }Note: If you want to capture LLM events anonymously, omit
distinct_id/distinctIdwhen constructing the handler. See our docs on anonymous vs identified events to learn more. -
3
Run your graph
Required
Attach the handler through
configwhen you invoke the graph, inside the function that handles a turn. Becausecreate_react_agentruns the turn as a single root run, PostHog nests each tool call as an$ai_spanunder the trace automatically, with real latency.Python
from langgraph.prebuilt import create_react_agent from langchain_openai import ChatOpenAI from langchain_core.tools import tool @tool def get_weather(city: str) -> str: """Get the weather for a given city.""" return f"It's always sunny in {city}!" model = ChatOpenAI(api_key="your_openai_api_key") agent = create_react_agent(model, tools=[get_weather]) def ask(user_input: str, user_id: str, conversation_id: str) -> str: handler = create_handler(user_id=user_id, session_id=conversation_id) result = agent.invoke( {"messages": [{"role": "user", "content": user_input}]}, config={"callbacks": [handler]}, ) return result["messages"][-1].content print(ask("What's the weather in Paris?", "user_123", "conversation-abc"))Node
import { createReactAgent } from '@langchain/langgraph/prebuilt' import { ChatOpenAI } from '@langchain/openai' import { tool } from '@langchain/core/tools' import { z } from 'zod' const getWeather = tool( (input) => `It's always sunny in ${input.city}!`, { name: 'get_weather', description: 'Get the weather for a given city', schema: z.object({ city: z.string().describe('The city to get the weather for'), }), } ) const model = new ChatOpenAI({ apiKey: 'your_openai_api_key' }) const agent = createReactAgent({ model, tools: [getWeather] }) async function ask(userInput: string, userId: string, conversationId: string): Promise<string> { const handler = createHandler(userId, conversationId) const result = await agent.invoke( { messages: [{ role: 'user', content: userInput }] }, { callbacks: [handler] } ) return result.messages[result.messages.length - 1].content } console.log(await ask("What's the weather in Paris?", 'user_123', 'conversation-abc'))PostHog automatically captures an
$ai_generationevent along with these properties:| Property | Description | | --- | --- | |
$ai_model| The specific model, likegpt-5-miniorclaude-4-sonnet| |$ai_latency| The latency of the LLM call in seconds | |$ai_time_to_first_token| Time to first token in seconds (streaming only) | |$ai_tools| Tools and functions available to the LLM | |$ai_input| List of messages sent to the LLM | |$ai_input_tokens| The number of tokens in the input (often found in response.usage) | |$ai_output_choices| List of response choices from the LLM | |$ai_output_tokens| The number of tokens in the output (often found inresponse.usage) | |$ai_total_cost_usd| The total cost in USD (input + output) | | [...] | See full list of properties |The handler also builds a trace hierarchy automatically based on how you structure your graph. Pass the same
$ai_session_idto every handler you construct for a conversation, to group its calls into one session. Passtrace_id/traceIdtoo, to control the top-level trace ID instead of letting PostHog generate one. -
Verify traces and generations
Recommended
Confirm LLM events are being sent to PostHog
Let's make sure LLM events are being captured and sent to PostHog. Under AI Observability, you should see rows of data appear in the Traces and Generations tabs.
LLM generations in PostHog
-
4
Next steps
Recommended
Now that you're capturing AI conversations, continue with the resources below to learn what else AI Observability enables within the PostHog platform.
| Resource | Description | | --- | --- | | Basics | Learn the basics of how LLM calls become events in PostHog. | | Generations | Read about the
$ai_generationevent and its properties. | | Traces | Explore the trace hierarchy and how to use it to debug LLM calls. | | Spans | Review spans and their role in representing individual operations. | | Anaylze LLM performance | Learn how to create dashboards to analyze LLM performance. |