stakeout-agent 0.0.3a0

Drop-in monitoring for GenAI applications

stakeout-agent

Drop-in monitoring for LangGraph applications. Captures every graph run, node execution, and tool call into MongoDB with no changes to your graph code.

Why stakeout-agent?

When building LangGraph applications, understanding how your graphs execute is critical for debugging and optimization. stakeout-agent provides:

• Zero code changes — just add a callback to your graph config
• Complete visibility — captures node starts/ends, tool calls, and errors
• Resilient by default — MongoDB failures are logged and never crash your application
• MongoDB storage — leverage your existing infrastructure
• Framework-agnostic core — easily extensible to other frameworks

Installation

pip install stakeout-agent

Requires Python 3.10+ and a running MongoDB instance.

Quick start

Sync (graph.invoke)

from stakeout_agent import LangGraphMonitorCallback

monitor = LangGraphMonitorCallback(graph_id="my_graph", thread_id="thread_123")
result = graph.invoke(inputs, config={"callbacks": [monitor]})

Async (graph.ainvoke / graph.astream)

from stakeout_agent import AsyncLangGraphMonitorCallback

monitor = AsyncLangGraphMonitorCallback(graph_id="my_graph", thread_id="thread_123")
result = await graph.ainvoke(inputs, config={"callbacks": [monitor]})

Try the example

A self-contained example graph is included to verify everything is wired up correctly.

Start MongoDB, then run:

docker compose up -d mongo
cd stakeout-agent
uv run python examples/dummy_app.py

It runs a three-node graph (with a tool call), then prints the runs and events documents written to MongoDB so you can confirm monitoring is working before integrating into your own application.

Configuration

Environment variable	Default	Description
MONGO_URI	mongodb://localhost:27017	MongoDB connection string
MONGO_DB	stakeout	Database name

What gets recorded

runs collection

One document per graph invocation.

{
  "_id": "<run_id>",
  "graph_id": "my_graph",
  "thread_id": "thread_123",
  "status": "completed",
  "started_at": "2026-04-25T10:00:00Z",
  "ended_at": "2026-04-25T10:00:05Z",
  "error": null,
  "metadata": {}
}

status is one of running, completed, or failed.

events collection

One document per node start/end, tool call, or error within a run.

Start events:

{
  "run_id": "<run_id>",
  "graph_id": "my_graph",
  "event_type": "node_start",
  "node_name": "agent",
  "timestamp": "2026-04-25T10:00:02Z",
  "payload": {"inputs": "..."},
  "error": null
}

End events include a latency_ms field measuring execution time:

{
  "run_id": "<run_id>",
  "graph_id": "my_graph",
  "event_type": "node_end",
  "node_name": "agent",
  "timestamp": "2026-04-25T10:00:03Z",
  "latency_ms": 1240.5,
  "payload": {"outputs": "..."},
  "error": null
}

event_type	When	latency_ms
node_start	A graph node begins execution	absent
node_end	A graph node completes	present
tool_call	A tool is invoked	absent
tool_result	A tool returns a result	present
error	A node or tool raises an exception	present

Error handling

All MongoDB write operations catch PyMongoError and log the failure rather than propagating the exception. A monitoring failure will never take down your application. Enable DEBUG logging on stakeout_agent to see these errors:

import logging
logging.getLogger("stakeout_agent").setLevel(logging.DEBUG)

Using MonitorDB directly

from stakeout_agent import MonitorDB

db = MonitorDB()

# fetch all runs for a graph
runs = list(db.runs.find({"graph_id": "my_graph"}).sort("started_at", -1))

# fetch events for a specific run
events = list(db.events.find({"run_id": "<run_id>"}).sort("timestamp", 1))

Package structure

stakeout_agent/
├── callback_handler/
│   ├── base.py        # _MonitorBase — framework-agnostic core logic
│   ├── langgraph.py   # LangGraphMonitorCallback, AsyncLangGraphMonitorCallback
│   └── __init__.py
└── db.py              # MonitorDB

To add support for another LLM framework, create a file under callback_handler/ that inherits from _MonitorBase and implements the target framework's callback protocol.

Dashboard

The recorded data can power a dashboard to visualize graph runs, node execution timelines, and tool call details:

License

MIT