Skip to main content
RootSign records every call to a LangChain BaseTool, whether LangGraph’s ToolNode makes the call or your own code does. You pass your tool list through rootsign.wrap_tools(), open a rootsign.session() around the run, and the graph runs as before. Tool names, descriptions and argument schemas are untouched, so the model sees the same tools.

Supported versions

The contract suite runs on Python 3.12. See supported Python versions for the rest of the SDK.

Install

Instrument your agent

This is a complete agent. It runs offline because the model node is scripted: it asks for two tools, then answers. Everything else is a normal LangGraph graph with ToolNode and tools_condition, which is the path RootSign intercepts in a production agent.
agent.py
The three RootSign lines are rootsign.init(...), async with rootsign.session(...), and rootsign.wrap_tools([...]) around the list you give ToolNode. To use a real model, replace scripted_model with a node that calls a chat model bound to the same tools; the RootSign lines stay the same. Run it:

Verify the session

The model’s decisions and the final answer are not recorded. RootSign records tool calls: what ran, with which arguments, and what it returned.

Two ways to instrument tools

Both produce the same records. Use whichever fits where your tools are defined.
rootsign.trace() must sit above @tool, so it receives the finished BaseTool. A tool that is already instrumented is skipped by wrap_tools(), so it is never recorded twice.

LangChain tools outside LangGraph

Instrumentation lives on the tool object, so calls you make yourself are recorded too:
lookup.py
Both .ainvoke() and .invoke() are recorded, once per call. The repository tests this with LangGraph; other LangChain runners that call .invoke() or .ainvoke() on the tool take the same path.

What gets recorded

Each call adds one ACTION_RECORD with the tool’s name as tool_name. The input is whatever the tool was called with:
  • From ToolNode, LangGraph passes the full tool call, so the arguments sit inside it along with the call ID:
  • From your own code, it holds the dictionary you passed, for example {"args": [{"order_id": "A-1001"}], "kwargs": {}}.
If the tool raises, the call is still recorded, with an empty output, and the exception reaches your graph unchanged. If RootSign cannot write the record, it logs a warning and the tool call completes normally.

How interception works

wrap_tools() replaces .invoke and .ainvoke on each tool instance in place and returns the same objects, so the tools stay BaseTool instances and ToolNode accepts them as before. The session and storage are looked up at each call, not when you wrap the tools, so you can build tools at import time. The design is in ADR-004.

Limitations

Calls must happen inside a session. A wrapped tool called outside async with rootsign.session(...) raises RootSignNotInitializedError, unless you pass ctx= and client= to wrap_tools() yourself.
  • Human approval is not available on BaseTool. @rootsign.trace(require_approval=True) on a LangChain tool raises NotImplementedError. Put the approval on the plain function the tool calls instead.
  • Prefer await tool.ainvoke() in async code. A sync .invoke() inside a running event loop works, because RootSign writes the record from a worker thread. On the PostgreSQL backend, do not share a SQLAlchemy AsyncSession across that boundary.

Full example

The agent above is examples/langgraph-jsonl in the repository, and CI runs it against every LangGraph line listed above. For a ReAct agent with a real OpenAI model on PostgreSQL, see examples/langgraph-invoice-agent.

Any Python function

Record calls to functions that are not LangChain tools.

How it works

What the hash covers and what each verdict means.