Skip to main content

AGENT SNOOP 🔍

Lightweight agent observability for any AI agent framework. Capture every step, tool call, and LLM invocation — store them in your own MongoDB or on liten.tech.

PyPI Python License: MIT


What does it do?

agent_snoop sits alongside your agent and records:

What Details
Steps Every LLM call, tool invocation, and agent action
Inputs / outputs What went in and what came out at every step
Tool calls Name, arguments, return value
Token usage Per-step and aggregated for the full run
Timing Start time, end time, and duration at every level
Full trajectory Ordered list of all steps for the entire invocation

Everything is stored as a single document per invocation, making it easy to query, visualise, and debug.


Installation

pip install agent-snoop[mongo,langgraph]

Quick start — 3 minutes

Step 1 — Pick your storage

You have two options. Choose one (or both):

Option A — Store traces in your own MongoDB (full data ownership)

If you already have a MongoDB instance (local, Atlas, or any hosted provider):

export MONGODB_URI="mongodb+srv://user:password@cluster.example.mongodb.net/"

agent_snoop will automatically create an agentsnoop_db database and a traces collection. Your data never leaves your infrastructure.

Option B — Store traces on liten.tech (zero infra, instant dashboard)

  1. Sign up at liten.tech/signup
  2. Go to Dashboard → Settings → API Keys and create a new key
  3. Export it:
export AGENTSNOOP_API_KEY="as_your_key_here"

If you set both, AGENTSNOOP_API_KEY takes priority.


Step 2 — View your traces on liten.tech

Go to liten.tech/traces and connect your storage:

  • If you used Option A (your MongoDB): go to Settings → Connect Database and paste the same URI. liten.tech will read traces directly from your database — your data stays where it is.
  • If you used Option B (API key): your traces are already there. Just sign in.

Step 3 — Add two lines to your agent code

import agent_snoop
from agent_snoop.integrations.langgraph import AgentSnoopCallbackHandler

# Reads MONGODB_URI or AGENTSNOOP_API_KEY automatically
tracer = agent_snoop.init(agent_name="my-agent", framework="langgraph")

query = "Your question here"

handler = AgentSnoopCallbackHandler(
    handle=tracer.trace(input=query)
)

result = await graph.ainvoke(
    {"messages": [HumanMessage(content=query)]},
    config={"callbacks": [handler]},
)

handler.on_chain_end_final(result)

That's it. Open liten.tech/traces to see your traces.


Integration styles

Captures every node, tool call, and LLM invocation in real time:

import agent_snoop
from agent_snoop.integrations.langgraph import AgentSnoopCallbackHandler
from langchain_core.messages import HumanMessage

tracer = agent_snoop.init(agent_name="my-agent", framework="langgraph")
query = "What caused the 2008 financial crisis?"

handler = AgentSnoopCallbackHandler(handle=tracer.trace(input=query, tags=["prod"]))

result = await graph.ainvoke(
    {"messages": [HumanMessage(content=query)]},
    config={"callbacks": [handler]},
)

handler.on_chain_end_final(result)

Post-run (zero agent changes)

Run your graph exactly as before, then hand the output to agent_snoop:

from agent_snoop.integrations.langgraph import parse_langgraph_output

result = await graph.ainvoke({"messages": [HumanMessage(content=query)]})
trace = parse_langgraph_output(result, input=query, agent_name="my-agent")
tracer.log_trace(trace)

Manual context manager (full control)

with tracer.trace(input=query, tags=["prod"]) as t:
    result = my_agent.run(query)
    t.set_output(result)
    t.set_metadata(user_id="u123")

What gets stored

Each trace is a single MongoDB document:

{
  "_id": "550e8400-e29b-...",
  "agent_name": "my-research-agent",
  "framework": "langgraph",
  "input": "What caused the 2008 financial crisis?",
  "output": "The 2008 financial crisis was caused by...",
  "status": "success",
  "started_at": "2024-01-15T10:23:00Z",
  "ended_at": "2024-01-15T10:23:04Z",
  "duration_ms": 4021,
  "total_token_usage": { "prompt_tokens": 812, "completion_tokens": 234, "total_tokens": 1046 },
  "tags": ["prod"],
  "steps": [
    {
      "step_index": 0,
      "step_type": "llm_call",
      "node_name": "researcher",
      "duration_ms": 1823,
      "token_usage": { "prompt_tokens": 412, "completion_tokens": 134, "total_tokens": 546 },
      "tool_calls": [
        {
          "tool_name": "web_search",
          "tool_input": { "query": "2008 financial crisis causes" },
          "tool_output": "...",
          "duration_ms": 341
        }
      ]
    }
  ]
}

Framework support

Framework Status
LangGraph ✅ Supported (callback + post-run)
AutoGen 🔜 Coming soon
CrewAI 🔜 Coming soon

License

MIT

Metadata

Release files for agent-snoop 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-snoop 0.1.1
File Size Uploaded Provenance Actions
agent_snoop-0.1.1.tar.gz 21.8 kB Without provenance Details for agent_snoop-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-snoop 0.1.1
File Interpreter ABI Platform Actions
agent_snoop-0.1.1-py3-none-any.whl Python 3 none any Details for agent_snoop-0.1.1-py3-none-any.whl

Total release size: 41.6 kB

Release files / agent_snoop-0.1.1.tar.gz

Download URL agent_snoop-0.1.1.tar.gz
Size 21.8 kB
Tags Source
SHA-256 checksum
How to use checksums
aff764d667f45713f5236c35c171cd5b83e4293ad459ee98822faad1ca4f9617
BLAKE2b-256 checksum
How to use checksums
0fe01b003686d246b71b9948ef3796fe887341601f1dbb563c706d45d63b97eb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.9.6

Release files / agent_snoop-0.1.1-py3-none-any.whl

Download URL agent_snoop-0.1.1-py3-none-any.whl
Size 19.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
12f080d91e5c2d1c71da7072f5cfb737fdd200e66b1e2d1bb6f28d6173a32b05
BLAKE2b-256 checksum
How to use checksums
92261e43e8970435e937f89f2a7d69bb190ce024b1ec55c698f541da70df23c8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.9.6

Security for agent-snoop 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page