DEV Community

Cover image for A Zero-Dependency Tracing CLI for AI Agents in Python
Xomebel Flora
Xomebel Flora

Posted on

A Zero-Dependency Tracing CLI for AI Agents in Python

#python #webdev #opensource #tutorial

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}")
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

severn
Enter fullscreen mode Exit fullscreen mode

This launches an interactive menu where you can:

  1. Verify active runtime status across your project.
  2. View your local telemetry database (severn_traces.jsonl) directly in the terminal.
  3. Explore multi-step agent topologies tailored for CrewAI, LangChain, and AutoGen architectures.
  4. 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.

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! ⚡

Top comments (0)