LangChain

Install the integration extra:

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

LangChain Agent Executor

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="sk-xxxxxxxxxxxxxxxx",
)
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`
`error`	Exception message if `on_chain_error` fires
`knowledgeRetrievals`	Each `on_retriever_start` / `on_retriever_end` pair - a failed retrieval (`on_retriever_error`) is recorded too, as a step with `output: "ERROR: ..."`, instead of being dropped

`AgentXCallbackHandler` reference

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

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 (max 16 KB)
`session_id`	Links traces from the same conversation thread in the UI

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