LangChain

Install the integration extra:

pip install "agentx-python[langchain]" langchain langchain-openai

LangChain Agent Executor

import os

from agentx import AgentX
from agentx.integrations.langchain import AgentXCallbackHandler
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
from langchain.agents import create_agent

client = AgentX.from_env()  # AGENTX_API_KEY (+ AGENTX_API_BASE_URL for self-host)

handler = AgentXCallbackHandler(
    tracer=client.tracer,
    name="support-agent",  # custom name for the agent
    session_id="session-001",  # custom session id for the agent
)

@tool
def policy_lookup(topic: str) -> str:
    """Look up a company policy by topic."""
    db = {
        "cancel": "Go to Account → Subscription → Cancel.",
        "trial": "14-day free trial, no credit card required.",
        "refund": "Full refund within 30 days.",
    }
    for key, val in db.items():
        if key in topic.lower():
            return val
    return "No policy found."


llm = ChatOpenAI(
    model="gpt-4o-mini",
    temperature=0,
    api_key=os.environ["OPENAI_API_KEY"],
)
agent = create_agent(
    llm,
    tools=[policy_lookup],
    system_prompt="You are a helpful support agent.",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "How do I cancel my subscription?"}]},
    config={"callbacks": [handler]},
)
print(result["messages"][-1].content)

client.tracer.flush(timeout=10)

LangChain Expression Language

from agentx import AgentX
from agentx.integrations.langchain import AgentXCallbackHandler
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

client = AgentX.from_env()

handler = AgentXCallbackHandler(
    tracer=client.tracer,
    name="support-chain",
    session_id="session-001",
)

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful support agent."),
    ("human", "{question}"),
])
chain = prompt | llm | StrOutputParser()

result = chain.invoke(
    {"question": "How do I cancel my subscription?"},
    config={"callbacks": [handler]},
)
print(result)

client.tracer.flush(timeout=10)

One AgentXCallbackHandler instance can be reused across multiple invocations. Pass it via LangChain’s standard config={"callbacks": [...]}; no changes to the chain or agent definition are required.

LangGraph

The same handler covers LangGraph (create_agent / create_react_agent) - pass it in the invoke config exactly as above. LangGraph runs arrive as a real span tree: each graph node becomes a child span, and every LLM call, tool call, and retrieval is parented under the node that ran it, so the trace dialog’s Timeline and Graph views show the actual graph trajectory. Plumbing runnables (RunnableSequence, ChannelWrite, …) are filtered out automatically.

agent = create_agent(ChatOpenAI(model="gpt-4o-mini"), tools=[lookup_order])
agent.invoke(
    {"messages": [("user", "Where is order A-1001?")]},
    config={"callbacks": [handler]},
)

What gets traced

Each top-level chain invocation produces one trace - a root span plus child spans for graph nodes (LangGraph), LLM calls, tool calls, and retrievals, with real per-step timings. Tool calls are additionally mirrored onto the root’s flat toolCalls list, which the Tool-failure check and trajectory matching read.

Field	Source
`input`	`inputs` dict from `on_chain_start`
`output`	`outputs` dict from `on_chain_end`
`latencyMs`	Wall-clock time from chain start to end
`model`	Extracted from the first LLM call’s serialized metadata
`toolCalls`	Each `on_tool_start` / `on_tool_end` pair, with `name`, `input`, `output`, `latencyMs`
`inputTokens` / `outputTokens`	Summed from each LLM call’s `LLMResult` usage (checked under `token_usage`, `usage`, and per-generation info, so OpenAI, Anthropic, and Gemini chat models all report)
`framework`	Stamped `langchain` automatically - the platform label on the framework filter and Monitor’s Platforms chart
`error`	Exception message if `on_chain_error` fires
`metadata.tools`	The first LLM call’s `invocation_params.tools` definitions, captured onto the trace metadata for the unregistered-tool listing (Tools & MCPs)
`retrieval` child spans	One per retriever run - what the RAG judges’ `{context}` reads. A failed retrieval (`on_retriever_error`) is recorded as a step with `output: "ERROR: ..."` instead of being dropped

The root span is stamped span kind agent, and each child span states its own kind: LLM calls as llm, tool executions as tool, retriever runs as retrieval, LangGraph nodes as chain. A chain run invoked inside an active with tracer.trace(...) span does not send an independent trace - it folds into that span as child spans instead, so an orchestrator wrapping several chain/agent/retriever calls gets one combined trace.

`AgentXCallbackHandler` reference

AgentXCallbackHandler(
    tracer: Tracer,
    name: str = "langchain-agent",
    metadata: dict | None = None,
    session_id: str | None = None,
    max_run_age_seconds: float = 3600.0,
)

Parameter	Description
`tracer`	`client.tracer` from your `AgentX` instance
`name`	Label shown in the AgentX UI for every trace sent by this handler
`metadata`	Static key-value metadata attached to every trace (stored truncated above 100,000 serialized characters - `AGENTX_INGEST_MAX_FIELD_CHARS`)
`session_id`	Links traces from the same conversation thread in the UI
`max_run_age_seconds`	Housekeeping bound: run state older than this is discarded, so a callback that never fires its end event can’t leak memory in a long-running server

Call tracer.flush() before your process exits in scripts or one-shot jobs. In long-running servers it is not required: traces drain automatically in the background.

Tracing

Framework Integrations

LangChain Agent Executor

LangChain Expression Language

LangGraph

What gets traced

`AgentXCallbackHandler` reference

​LangChain Agent Executor

​LangChain Expression Language

​LangGraph

​What gets traced

​AgentXCallbackHandler reference

LangChain Agent Executor

LangChain Expression Language

LangGraph

What gets traced

`AgentXCallbackHandler` reference