tracesage: See Inside Your LangGraph Agents

Talking Shop
1

As LangGraph applications grow from simple prototypes into production systems, debugging becomes increasingly difficult.

A single user request may involve:

  • Multiple agents
  • Tool calls
  • Retrieval pipelines
  • MCP servers
  • Several LLM invocations
  • Conditional graph routing

When something goes wrong, developers need visibility into what happened.

Today, the most common solution is to add logging everywhere, inspect terminal output, or integrate a full observability platform.

But what if you just want to see what your agent is doing right now?

That’s the problem Tracesage was built to solve.

The Problem

LangChain and LangGraph already emit a rich callback stream:

  • Chain start/end
  • Tool start/end
  • LLM start/end
  • Retrieval events
  • Errors
  • State transitions

Most developers never see this information because it is buried inside callbacks.

As workflows become more complex, understanding execution becomes harder:

  • Which tool was called?
  • Which node took the longest?
  • Why did the graph follow this path?
  • Which MCP server provided this tool?
  • Where did the error originate?

Traditional logging answers some of these questions.

Tracing answers all of them.

Getting Started

Install Tracesage:

pip install tracesage[langchain]

Requires Python 3.11+.

Adding Observability to an Existing Graph

Suppose you already have a LangGraph workflow:

result = await graph.ainvoke(
    {"input": payload}
)

Adding Tracesage requires only one callback:

from tracesage import TraceSage

tracer = await TraceSage.create()

result = await graph.ainvoke(
    {"input": payload},
    config={"callbacks": [tracer.handler]},
)

Open:

http://localhost:7842/ui

and watch the execution trace appear in real time.

Zero-Infrastructure Tracing

One design goal behind Tracesage is simplicity.

There is:

  • No Docker
  • No Postgres
  • No cloud account
  • No external collector

Just:

pip install tracesage[langchain]

and start tracing.

Trace data is persisted locally using SQLite and compressed storage so traces remain available after application shutdown.

Capturing Everything Automatically

For scripts and notebooks, Tracesage can capture LangChain activity globally.

import tracesage

with tracesage.trace() as tl:
    result = agent.invoke("your input")

    input(
        "Trace ready — open the printed link, then press Enter"
    )

Every LangChain call inside the block is captured automatically.

Understanding Agent Topology

One of the most useful concepts in Tracesage is the topology graph.

Every execution component is classified into a small set of node types:

  • Agent
  • Tool
  • LLM
  • Retriever
  • Chain
  • MCP Server

This allows developers to quickly understand how a workflow executed and how different components interact.

For example:

Agent
 ├── Tool
 ├── Tool
 ├── Retriever
 └── LLM

Instead of scrolling through logs, developers can inspect execution visually.

MCP-Aware Observability

As MCP adoption grows, tracing becomes more challenging.

A workflow may contain:

  • Local tools
  • Tools loaded from multiple MCP servers
  • Dynamic tool discovery

Tracesage automatically attributes tools to their originating MCP servers.

This makes it possible to answer questions like:

  • Which MCP server provided this tool?
  • Which agents are using this server?
  • Which server generated an error?

without additional instrumentation.

ui-topology
ui-topology1600×1039 192 KB

Developer Workflow

Tracing is useful during development, but Tracesage also provides CLI tooling for investigation.

Render a trace as a tree:

tracesage show <run_id>

Watch a run live:

tracesage watch <run_id>

Compare two runs:

tracesage diff <run_a> <run_b>

Open exported traces:

tracesage view trace.jsonl

This makes debugging possible without leaving the terminal.

Testing Agent Behavior

Tracesage also includes a pytest fixture that allows trace assertions in tests.

def test_agent_uses_search(tracesage_capture):
    agent.invoke("find me a hotel")

    tracesage_capture.assert_tool_called("search")
    tracesage_capture.assert_no_errors()

This makes it possible to validate agent behavior beyond simple output checking.

Conclusion

Observability is becoming a core requirement for production AI systems.

As LangGraph workflows become larger and more dynamic, developers need tools that help them understand:

  • What happened?
  • Which components executed?
  • Where did failures occur?
  • How did the graph evolve over time?

Tracesage provides a local-first approach to answering those questions with minimal setup and deep integration into the LangChain ecosystem.

Install it:

pip install tracesage[langchain]

GitHub:

PyPI: