A Zero-Dependency Tracing CLI for AI Agents in Python

Xomebel Flora — Thu, 22 Oct 2026 10:41:04 +0000

Zero-Dependency Tracing CLI for AI Agents in Python (`severn-trace`)

If you've ever built an autonomous AI agent using LangChain, CrewAI, or AutoGen, you know the absolute chaos of debugging execution loops.

Your agent calls a tool, the tool throws a malformed JSON payload, the loop breaks, and you're left staring at a wall of unstructured stack traces. If you try to fix this by installing heavy APM tools, you spend 20 minutes configuring API keys, setting up cloud endpoints, and wrestling with third-party dependency conflicts.

When you're building fast—especially during a hackathon—you don't need cloud dashboard bloat. You need instant, local feedback.

That’s why severn-trace, an ultra-lightweight, zero-dependency Python tracing runtime and interactive terminal CLI. Here is how it works and how it simplifies agent debugging.

The Philosophy: Pure Standard Library & Zero Friction

Most monitoring tools force you to bring your own baggage: database connections, external collector middleware, or complex YAML configuration files.

severn-trace takes the opposite approach. It relies strictly on the Python standard library (json, time, functools, os). That means:

Zero dependency conflicts with fast-moving LLM libraries.
Instant setup via a single shell command.
A local fallback ledger (severn_traces.jsonl) that stores your agent telemetry securely on your machine.

Building an Agent Step Decorator in 30 Seconds

To start tracing any agent tool call or critical function, you don't need to rewrite your agent logic. You just import the trace decorator:

from severn import trace
import random

@trace
def autonomous_search_agent(query: str):
    # Simulate an agent tool lookup
    if random.random() > 0.5:
        raise ConnectionError("API rate limit exceeded during tool execution.")
    return f"Successfully retrieved context for: {query}"

if __name__ == "__main__":
    for i in range(3):
        try:
            autonomous_search_agent(f"Query vector #{i}")
        except Exception as e:
            print(f"Caught agent exception: {e}")

Every single time that function runs, severn-trace automatically captures:

Execution duration (timing metrics)
Success vs. failure status (SUCCESS or FAILED)
Detailed error exceptions and arguments

...and appends them straight to your local severn_traces.jsonl file.

Meet the Interactive CLI (`severn`)

Instead of making you dig through raw JSON log files, severn-trace comes with a built-in cyberpunk interactive terminal dashboard.

Once you install it globally via pipx:

pipx install severn-trace

You can run the global command from anywhere on your machine:

severn

This launches an interactive menu where you can:

Verify active runtime status across your project.
View your local telemetry database (severn_traces.jsonl) directly in the terminal.
Explore multi-step agent topologies tailored for CrewAI, LangChain, and AutoGen architectures.
Access community support and hackathon portals (like Lablab.ai).

Wrap-Up & Try It Out

If you're tired of heavyweight monitoring tools slowing down your local development or hackathon builds, give severn-trace a spin.

PyPI Package: pip install severn-trace
GitHub Repository: github.com/davidamadie06/severn-trace
Community Discord: Connect via @severnteam

Drop a star on GitHub if you find it helpful for your agent projects, and let me know how you're using it in your builds! ⚡

DEV Community: Xomebel Flora