Debugging

How do I debug my AI agent when it does weird things?

Pick one bad run and read it in order. Give that run an id, record each tool call, decision, message, and error with a timestamp, and stop at the first step that is wrong. The final reply hides that step.

The steps work with any log you can order by time. The product notes are what AgentTracer stores and alerts on. It is hosted only. Model calls do not pass through it. If you need token cost, start with AI agent observability tools. A model-call record is on what is LLM observability?

A repeated tool name on one run is the other common failure. That case is how do I catch an AI agent stuck in a loop? The production checklist is on how to monitor AI agents.

Steps

  1. Isolate one run. Copy the id your app already uses for that conversation, or mint a new one. Without a run id, events from two conversations land in one pile. On POST /api/v1/events, AgentTracer accepts run.id at 1 to 128 characters. The project timeline prints that id under the event name when you send it.
  2. Record every step. Send one event per tool call, decision, message, and error, and put a timestamp on each. The order is the trace. Recommended types are tool_call, decision, message, error, and span. Other type strings are stored. A name is optional. Up to 100 events can ride in one request, and the request body must stay under 1,000,000 characters.
  3. Keep the payload small. Include the argument that explains the step, not the whole document. Do not put secrets, raw credentials, or customer secrets in the payload. AgentTracer stores the JSON you send and does not redact it. It does not pull prompts out as their own fields, and it does not compute token cost.
  4. Read the newest events. Stop at the first step that is wrong. The project timeline lists up to 100 events, newest first, with the time, the type, the name, and the payload. A payload longer than 180 characters is cut off on that screen. There is no separate page for one run, and there is no filter. The run id on the row is how you keep one conversation together.
  5. Alert when the pattern changes. AgentTracer checks once a day, around 15:00 UTC. The default window is the last 24 hours, compared with the previous 7 windows. It flags an error-rate spike, a volume spike, a volume drop, or an agent that went silent. A project can change those thresholds. The check does not page you for one weird step. It has no detector for loops, dollar cost, or risky tools.

The Monday digest, around 14:00 UTC, covers the trailing 7 days: event counts, top tool names, recent errors, and anomalies. The same summary is in the dashboard. You can turn the email off. The daily alert email is separate, and you can turn that off too.

curl -sS -X POST https://agenttracer.net/api/v1/events \
  -H "Authorization: Bearer $AGENTTRACER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent":{"id":"support-bot"},"run":{"id":"run_01h"},"events":[{"type":"tool_call","name":"search_docs","timestamp":"2026-10-29T00:12:00.120Z","payload":{"query":"refund policy"}},{"type":"error","name":"empty_result","timestamp":"2026-10-29T00:12:00.880Z","payload":{"reason":"no hits"}}]}'

Checklist

What to check when an agent does something weird, and what AgentTracer records
What you are checkingWhat to doWhat AgentTracer adds
One weird runRead that run in time order and stop at the first wrong step.Project timeline of the newest 100 events. The run id is on the row when you sent one.
Errors climbingCompare the error rate with a recent baseline. An alert on every error gets ignored.Daily error-rate spike. The latest window needs at least 20 events, an error rate of at least 20%, and a rate at least 2× the baseline. An event counts as an error when its type is error, any case.
A burst of callsCount events. Volume is the signal you can see without a price list.Daily volume spike. The baseline average has to be above zero, the latest window needs at least 20 events, and volume has to be at least 3× that average.
Volume fell offCompare the latest window with the recent average.Daily volume drop. The baseline needs to average at least 30 events a window, and the latest window has to be at or below 25% of that average.
An agent that stoppedNotice a busy agent that then sends nothing.Silence. An agent needs at least 5 events in the previous 24 hours and zero in the last 24 hours. Only events sent with an agent id count. If you omit the agent name, the id is used as the name.
A tool you care aboutRecord that call. A monitor cannot guess which tools matter.The call is on the timeline only if you sent it. There is no risk score.

Questions

How do I debug an AI agent that did something weird?

Give the run an id and record each tool call, decision, message, and error with a timestamp. Then read those steps in order and stop at the first one that is wrong. The final message is the symptom. AgentTracer stores the events you POST and lists the newest 100 on the project timeline.

What does AgentTracer alert on?

Four kinds, on a daily check around 15:00 UTC: an error-rate spike, a volume spike, a volume drop, and an agent that went silent. The defaults compare the last 24 hours with the previous 7 windows. A project can change the thresholds. There is no alert for a single weird step, and no loop detector. A weekly digest goes out on Monday around 14:00 UTC with event counts, top tool names, recent errors, and anomalies.

Does AgentTracer show the prompt or the token cost?

It stores the JSON payload you attach to an event. It does not pull prompts out as their own fields, it does not redact that payload, and it does not compute token cost. Do not send secrets. Volume is the closest signal to a cost spike when you are not pricing tokens.

Will sending events slow the agent down?

Send them in the background and the agent does not wait. AgentTracer is not a proxy, so model calls never pass through it. There is no official SDK. Each event is a small HTTP request with a project API key. Send it without waiting for the reply, or give it a short timeout.

Where are the related pages?

The production checklist is on how to monitor AI agents. A model-call record is on what is LLM observability? A wider tool list is on AI agent observability tools. Plan limits are on the pricing page.