before you rewrite your agent's system prompt for the 37th time, figure out what actually failed.
here's the debugging checklist i'd keep next to every agent project:
1. expected result: what should have changed in the real system?
2. actual result: did that change happen, or did the agent just say it did?
3. tool inputs: were the arguments valid and were the required IDs available?
4. execution: did the API reject the call, time out, or return an error in its response?
5. recovery: did the agent retry, switch tools, or continue as if nothing happened?
6. recurrence: has the same failure happened across other requests?
now save the failing request as a regression test before changing anything.
Ratel helps with that last investigation by surfacing recurring execution patterns across runs.
a better prompt might be the fix. but you should probably find the bug first. 🦡
the AI devtool industry has gotten very good at showing you everything your agent did.
beautiful timelines. thousands of spans. absolutely gorgeous ways to watch your agent make the same mistake again.
we're building Ratel toward the next part: spotting recurring problems, working out what should change, and testing whether the change actually helps.
the badger appreciates the traces.
he wants the fix. 🦡
1/6 if your agent performs the exact same 4-step routine every run, congratulations. you may have built a very expensive for-loop. 🦡
here's how to decide whether those steps belong in code instead of another model decision. 🧵
5/6 before combining anything, check permission boundaries and failure recovery.
a single combined operation can be worse if it hides partial writes or removes useful checkpoints. test the whole transaction.
if an agent keeps botching release closeouts, adding “be more careful” to the prompt is not a debugging strategy.
Ratel groups all the runs for a specific job and extracts insights from those.
now you have a specific workflow to investigate instead of vaguely blaming the model. 🦡
your users keep asking for the same damn thing and your logs make it look like ten different jobs
we group recurring requests in ratel's intent extraction preview so you can see the pattern across different wording, without reading every run by hand
tool search never showed the model the right tool. wtf was it supposed to pick?
in ratel, we put the missed queries next to the description. does it describe the job they're asking for?
that's where the proposed rewrite shown here starts
your agent burned through tokens.
cool. what did it actually accomplish?
cost, latency, and execution volume only tell part of the story.
Ratel brings those numbers together so you can start figuring out where the work is going. 🦡
Your AI agent can finish a run without actually finishing the job.
Every tool might execute successfully, and the final response can still miss what the user asked for.
A clean execution trace tells you the machinery ran. It doesn't prove the task was completed correctly.
That's a pretty important distinction when you're running agents in production. 🦡
You don't need to change your agent framework to start using Ratel.
Take the Vercel AI SDK adapter as an example.
It supports two ways to inject retrieved capabilities: appendRecall() adds them to the conversation history you can persist,
while prepareStep injects them for the current run.
Ratel also supports Mastra through a dedicated adapter, with TypeScript and Python SDKs for other integrations.
Your agent's playbooks shouldn't need a complete rebuild every time one changes.
Ratel's SkillCatalog.replaceAll updates the live skill catalog, removes deleted entries, and preserves cached embeddings for unchanged skills.
Only new or modified searchable content needs embedding work.
An unchanged catalog costs zero new embeddings.
A retrieval score of 1.0 doesn't mean your agent found the right tool.
Depending on the ranking method, it can simply mean "best of what came back."
That's why Ratel uses relevance instead of confidence. The score measures how well a capability matches the query, not the probability that the model will choose correctly.
Don't confuse ranking with certainty. 🦡
