https://github.com/fotsopatrick/agent-tracer
Démo: https://fotsopatrick.github.io/agent-tracer/
Everybody builds agents. Nobody sees them.
I have a small team of AI agents that work for me. They plan, they write code,
they review each other, they test. They have been talking to each other for
months.
Thousands of messages. Hundreds of pairs of agents talking. All of it stored in
rows and columns.
And that was the problem. I could read that a message had been refused.
I could not see it.
Reading status = REFUSED in row 4 812 of a table tells you nothing. You do not
feel where the work got stuck. You do not see that the same agent refuses the
same thing every single time. A table hides the shape of the conversation.
So I stole an idea from school
If you ever studied networks, you used Packet Tracer. You drop routers on a
canvas, you draw cables between them, you press play — and little envelopes
travel down the cables. When one gets dropped, you see it drop.
Nobody has to explain a network to you after that. You watched it.
I copied that idea, one word at a time:
| Packet Tracer | Agent Tracer |
|---|---|
| a device | an agent |
| a cable | a pair of agents that talk |
| a packet | one message |
| a dropped packet | a refusal — with |
That is the whole design. There is not
What it looks like
Agent Tracer is one HTML file. You open it in a browser and it starts
moving on its own: a demo conversationa reviewer
and a tester plays out, envelope by en
- Each agent is a box on the board.
- Each message is an envelope sliding
- Green envelope: the gate said ye
- Red envelope: the gate **refusedn on screen.
You can press Pause, press **Step*me, or click
any line in the log to jump straight to that moment.
No build step. No npm install. No dependencies. No server. It works with the
wifi off.
The part that actually matters: the
Most agent dashboards show you throughished, a
nice green line going up.
That is the least interesting half of
An agent that can only say yes is not oment your
system becomes trustworthy is the mome to say
no — and then tells you why it said no.
So Agent Tracer makes refusals the loudest thing on the screen. A red envelope
carries a why field, and that field is printed in full:
REFUSE — "the patch swallows the
why: a caught exception with an empg it or
re-raise it.
That one line is worth more than a hunly place
where the system teaches you something.
There is a sentence taped above my des
**A gate that never refused guards n
If you run your logs through this and you see zero red, you have not built a
safe system. You have built a system wested.
The seven words
The messages use a tiny vocabulary borrol*. In a
control tower, the controller gives a s it back
before turning. The readback is not poh a
misunderstanding before the plane
My agents talk the same way. Seven wor
| Word | Meaning |
|---|---|
ASK |
I ask you to do something |
READBACK |
Understood — I repeat y |
RUN |
I am doing it |
DONE |
Finished, here is the proof |
REFUSE |
I will not, and here is w |
BLOCKED |
I cannot continue, here |
DUNNO |
I do not know, and here is what would settle it |
The first four are easy. The last thre
DUNNO is my favourite. A model that l invent an
answer instead — and an invented answeion. So the
word exists, it is colour-coded, and it comes with a field for what would
settle it.
Feeding it your own logs
Drag a file onto the page, or use **Opaded — there
is no server to upload to, no fetch, no telemetry. The file is read in your
browser and stays there.
The format is deliberately boring. Plaer line:
json
{
"agents": ["planner", "coder", "revi
"messages": [
{ "from": "planner", "to": "coder
"subject": "add a retry to the f
{ "from": "coder", "to": "planner", "verb": "READBACK",
"subject": "understood: retry thdelay" },
{ "from": "reviewer", "to": "coder
"subject": "the patch swallows t
"why": "A caught exception with re." },
{ "from": "coder", "to": "plann
"subject": "how long should the delay be?",
"why": "Two values are defensiblervice SLA
would settle it." }
]
}
Three things make this easy to adopt:
1. agents is optional. Leave it out an
whoever appears in the messages.
2. verb is free text. The seven words lse
still shows up, just in a neutral c my
business.
3. why is optional but it is the most usal
without a reason teaches nobody anything.
If your framework already writes a trace — LangGraph, CrewAI, AutoGen, or your
own hand-rolled loop — turning it intoscript. Map
your sender to from, your receiver to error
message to why. That is the entire int
Try it
- Live demo: https://fotsopatrick.gith
- Source: https://github.com/fotsopatr
- Licence: Apache 2.0 — use it, change
Download the single file and it works sion of
anything to keep up to date.
Where this came from
Agent Tracer is the front door of some control
tower where a team of agents does real work behind gates that are allowed to
say no — automated checks, peer reviewwho has the
last word on anything that goes out.
The tracer is the window into that towdalone file
because the window turned out to be useful on its own, and because I would like
to know whether it is useful to you to
So: run your own agent log through it, see.
If the answer is "none", that is the f
Top comments (0)