How Vorlo works, in plain English

I built Vorlo because my LangChain agents kept dying with errors like ToolError: 403 and nothing else. This page explains what it actually does, with pictures, in the language I wish more tools used.

The problem, concretely

An agent isn't one program. It's a model making decisions, calling a chain of tools (an API here, a database there), each one able to fail in its own way. When step 9 of 12 breaks, the error you see is usually three words long, and the context that would explain it (what the model was thinking, what the previous step returned) is already gone.

So debugging an agent means reconstructing a crime scene from memory. Most people do it with print statements. I did too, for about a year.

What the two lines do

import vorlo_trace
vorlo_trace.init(api_key="vrlo_...", agent_name="my-agent")

That hooks Vorlo into your agent's callbacks. From then on, every run is recorded as a session: each tool call with its input and output, the model's reasoning before each decision, latency and token cost per step. Sends happen on a background thread with a bounded queue and a 2-second timeout. If Vorlo's server is unreachable, events get dropped silently and your agent doesn't notice. It cannot slow your agent down, and it cannot crash it.

When a step fails, the failure goes through a diagnosis pipeline:

Known failure shapes (expired keys, rate-limit loops, 404s from a bad ID) match a curated registry instantly, no AI involved. Failures nobody has seen before go to an LLM with the full step context, and that answer gets cached by error signature, so each new failure shape costs one model call ever. The result is the same either way: what happened in plain English, the root cause, and a specific fix.

The part I care most about: honest confidence

An LLM diagnosis is a hypothesis, and pretending otherwise is how tools lose your trust. So every diagnosis in Vorlo carries a label.

The promotion is the interesting bit. When a developer clicks "yes, this fix worked", or when Vorlo observes that a failing tool stopped failing right after a diagnosis (it watches for exactly this), the diagnosis becomes verified. Verified fixes outrank everything: the next person who hits the same error shape gets the fix that actually worked, not a fresh guess.

Why it gets better with use

Error signatures are normalized (IDs, timestamps and tokens stripped out), so the same failure shape maps to the same fingerprint no matter whose agent hit it. The fix library is shared. One developer confirms a fix in Berlin, and the same 403 in Bangalore comes back already solved.

This is also why I publish the common patterns openly in the Failure Index. The knowledge of how agents break shouldn't be a secret.

The editor loop

The package ships an MCP server (vorlo-mcp). If you use Claude Code or Cursor, you can ask "why did my last run fail" and your assistant pulls the diagnosis, proposes the patch, applies it, reruns your agent, and reports back whether the error actually stopped. That confirmation feeds the same library. The first time I watched the whole loop finish without me touching anything was the moment this stopped being a side project.

What it doesn't do (yet)

It supports LangChain (Python and JS) and the OpenAI Agents SDK. Nothing else yet. The verified-fix library is young; it grows with usage, which is the design, but I won't pretend it's huge today. And the SDK needs a free API key, so there's a signup. If you just want to see the kind of diagnoses it produces, the Failure Index is open, no signup.

Try it

pip install vorlo-trace     # Python
npm install vorlo-trace     # JS / TS

Free while in beta. If you run agents in production, I'd honestly like to hear where the diagnosis gets it wrong — that's the part I'm trying to get right. I'm alan.joshy@vorlo.dev.