Skip to main content
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(
    api_key="agx-xxxxxxxxxxxxxxxx",
    workspace_id="xxxxxxxxxxxx", # optional
)

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.

What gets traced

Each top-level chain invocation produces one trace. Nested chain calls and LLM calls are folded in — they are not sent as separate traces.
FieldSource
inputinputs dict from on_chain_start
outputoutputs dict from on_chain_end
latencyMsWall-clock time from chain start to end
modelExtracted from the first LLM call’s serialized metadata
toolCallsEach on_tool_start / on_tool_end pair, with name, input, output, latencyMs
errorException message if on_chain_error fires

AgentXCallbackHandler reference

AgentXCallbackHandler(
    tracer: Tracer,
    name: str = "langchain-agent",
    metadata: dict | None = None,
    session_id: str | None = None,
)
ParameterDescription
tracerclient.tracer from your AgentX instance
nameLabel shown in the AgentX UI for every trace sent by this handler
metadataStatic key-value metadata attached to every trace (max 16 KB)
session_idLinks 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.