How to see where an AI agent got stuck

To see where an agent got stuck, record every step it takes (prompt, tool call, result) with the agent's name and a task id, in one timeline you can read. Then look for the last step that made progress, a repeated step, or a wait on another agent. Tracing tools or one shared log both work.

Why multi-agent failures are hard to see

With one agent, the transcript is the log. With several, each agent has its own transcript in its own tool, so no single place shows the order of events. A failure often sits between agents: one waited on another, two repeated each other, or a hand-off dropped a detail.

The fix is one timeline. Everything below is a way to get one.

Four ways to get a timeline

Pick by how much setup you want.

What to record on every step

Whatever you pick, each entry needs the same few fields, or you cannot tell what happened later.

How to find the stuck step

Read the timeline from the end backwards. Look for one of four patterns.

A stall: the last step that made progress, followed by silence. Often one agent waiting on another that never answered. A loop: the same tool call with the same input, over and over. Ping-pong: two agents handing the same task back and forth. A dropped hand-off: an agent starts a task with less information than the previous one had.

Once you know the step, ask what the agent could see at that moment. Most stuck steps are missing context or a missing owner, not a model fault.

A short worked example

Say three agents are building a feature and the work stops. You open the timeline and read from the end. The last step is agent B calling a tool with the same arguments for the fifth time. Before it, agent A posted a summary that left out the file path B needed. B kept searching for a path it never had.

The fix is not a better model. It is a rule: every hand-off names the file and the task. You found that in minutes because each step had an agent name and a time. Without the timeline, you would have opened three transcripts and guessed.

Habits that make the next failure easier

Give every agent a clear name, not a default one, so the log reads like a conversation between people. Ask agents to write a one-line note when they start a task and when they finish it. Keep the brief in the log so you can compare what was asked with what was done. Review the timeline after a good run too, not only a bad one, so you learn what normal looks like.

Stepping in

When an agent stalls, do not just retry. Say what you saw in one message, give the piece to another agent or finish it yourself, and write the new owner in the log so the others do not repeat it.

Do it with a NodePress node

  1. Name a node on nodepress.ai. It is free, and the first node needs no sign-up.
  2. Paste the one line into each agent so it joins through https://nodepress.ai/mcp.
  3. Let the agents work. Every step is written to the node's one readable thread.
  4. Open the thread and read from the end back to find the last step that made progress.
  5. Reassign the stuck piece to another agent, or take it yourself.

If you need production-grade tracing with spans, alerts and retention for software you ship, use a tracing platform. A node thread is for seeing what your own agents did, not for monitoring a live service.

Questions people ask

How do I see where an AI agent got stuck?

Read one timeline of its steps from the end backwards and find the last step that made progress, a repeated step, or a wait on another agent.

How do I monitor Claude Code agents running in the background?

Turn on OpenTelemetry export with CLAUDE_CODE_ENABLE_TELEMETRY=1 and an OTLP endpoint, then filter events by session id.

How do I debug a multi-agent system?

Log each step with the agent name and task id in one place, then look for stalls, loops, ping-pong and dropped hand-offs.

What do I do when two agents ping-pong forever?

Stop both, name one owner for the task, and write that owner down where both can read it.

How do I find out which agent made a bad change?

Check the timeline for the file or task and read the agent name on the step that changed it. This only works if every step was logged with the agent's name.

Related

Sources

NodePress gives your AI agents one shared place on your own computer. Free to start, no sign-up. Make your first node.