Hady Walied

Posted on Nov 3

Announcing AgentHelm v0.2.0: Enhanced Observability and Developer Experience

#agents #tooling #ai #monitoring

Have you ever deployed an AI agent only to wonder what it's actually doing? Or struggled to debug why it made a particular decision? You're not alone.

We are excited to announce the release of AgentHelm v0.2.0! This release tackles the observability challenge head-on with powerful new features to help you build, debug, and monitor your agents with confidence.

What's New in v0.2.0?

This release brings a host of new features designed to give you deeper insights into your agent's execution and streamline your development workflow.

🚀 Storage Abstraction Layer

We've introduced a flexible storage abstraction layer that allows you to choose how your agent's execution traces are persisted. Whether you prefer simple JSON files for local development or a more robust SQLite database for efficient querying, AgentHelm has you covered.

JsonStorage: The default, file-based storage for traces.
SqliteStorage: A new backend that stores traces in a SQLite database, enabling powerful querying capabilities.

# Using JSON storage (default)
from orchestrator.core.storage import JsonStorage
storage = JsonStorage("my_traces.json")

# Or switch to SQLite for better querying
from orchestrator.core.storage import SqliteStorage
storage = SqliteStorage("my_traces.db")

🔍 CLI Trace Explorer

Debugging and analyzing agent behavior is now easier than ever with the new agenthelm traces command. This powerful CLI tool allows you to inspect, filter, and export your agent's execution traces directly from the command line.

Here's a quick look at what you can do:

List Traces: Get a quick overview of recent traces.

$ agenthelm traces list --trace-file examples/observability_example/observability_trace.db

```
+------+---------------------+------------------+----------+----------------------+ 
|   ID | Timestamp           | Tool Name        | Status   |   Execution Time (s) |
+======+=====================+==================+==========+======================+
|    0 | 2025-11-03 21:23:00 | undo_create_task | SUCCESS  |                    0 |
+------+---------------------+------------------+----------+----------------------+ 
|    1 | 2025-11-03 21:23:00 | create_task      | SUCCESS  |                    0 |
+------+---------------------+------------------+----------+----------------------+ 
|    2 | 2025-11-03 21:23:00 | search_web       | SUCCESS  |                    0 |
+------+---------------------+------------------+----------+----------------------+ 
|    3 | 2025-11-03 21:23:00 | get_current_time | SUCCESS  |                    0 |
+------+---------------------+------------------+----------+----------------------+ 
```

Show Trace Details: Dive deep into a specific trace to understand the agent's reasoning and actions.
```
$ agenthelm traces show 1 --trace-file examples/observability_example/observability_trace.db
```
Filter Traces: Find exactly what you're looking for with powerful filtering options.
```
$ agenthelm traces filter --tool-name create_task --status SUCCESS
```
Export Traces: Export your traces to JSON, CSV, or Markdown for further analysis or reporting.
```
$ agenthelm traces export --output failed_traces.csv --format csv --status FAILED
```

✨ New Observability Example

To help you get started with these new features, we've added a new example in examples/observability_example/. This example demonstrates how to use the new storage backends and provides a hands-on way to explore the CLI trace explorer.

Check out the observability_agent.py file to see how you can easily switch between JsonStorage and SqliteStorage and generate traces for different scenarios.

# from examples/observability_example/observability_agent.py

def run_example_agent(storage_type: str = "json"):
    logging.info(f"\n--- Running AgentHelm Observability Example with {storage_type.upper()} Storage ---")

    # 1. Setup Storage
    if storage_type == "json":
        trace_file = "observability_trace.json"
        # Clean up previous trace file if it exists
        if os.path.exists(trace_file):
            os.remove(trace_file)
        storage = JsonStorage(trace_file)
    elif storage_type == "sqlite":
        trace_file = "observability_trace.db"
        # Clean up previous trace file if it exists
        if os.path.exists(trace_file):
            os.remove(trace_file)
        storage = SqliteStorage(trace_file)
    else:
        logging.error("Invalid storage type. Use 'json' or 'sqlite'.")
        return

    # ... rest of the agent setup and execution

Why SQLite?

For production deployments with thousands of traces:

JSON: ⏱️ ~2.5s to filter 10,000 traces
SQLite: ⚡ ~0.05s to filter 10,000 traces (50x faster!)

Plus, SQLite enables powerful queries like finding all failed traces with low confidence scores in under a second.

Upgrading from v0.1.0

Good news! v0.2.0 is fully backward compatible. Simply upgrade:

Get Started Today!

We believe these new observability features will significantly improve your experience building and deploying reliable AI agents. To get started with AgentHelm v0.2.0, simply upgrade your installation:

pip install --upgrade agenthelm

What's Next?

This is just the beginning! We're already working on:

🌐 OpenTelemetry integration for distributed tracing
🔌 Model Context Protocol (MCP) support
📊 Web-based trace visualization dashboard
🎯 Advanced constraint validation system

Want to influence the roadmap? Join the discussion on GitHub!

Join the AgentHelm Community

Built something cool with AgentHelm? We'd love to hear about it! Share your story in our Show and Tell section.

DEV Community