> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug mode: replay a flow agent's call step by step

> Replay a flow agent's call on its flow with the recording, see what the model saw at each step, check tools, guardrails and reply times, and follow live calls.

Debug mode replays a flow agent's call on the flow it ran on. The step being heard lights up on the canvas while the recording plays, and beside it you see the conversation, every visit to a step, and the call's logs. Use it to find why a call took a wrong turn, what the model was told at a step, why a tool failed, or where replies were slow. On a call in progress, it follows the call on its flow as it happens.

## Before you start

* Debug mode is for [flow agents](https://docs.tryhamsa.com/agents/flow/overview.md). For a single prompt agent's call, use [call details](https://docs.tryhamsa.com/agents/monitor/call-details.md): the transcript, the recording, the logs and reply time.
* You need the **View** permission on the **Conversation log**. To open the version a call ran on in the editor, you also need **View** on agents. See [Roles and permissions](https://docs.tryhamsa.com/overview/projects/roles-and-permissions.md).

## Open debug mode

**1. Open the call**

In the [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md), click a flow agent's call. Its details open beside the list.

**2. Click Debug mode**

Click **Debug mode** at the end of the tab row. Or press Cmd+K (Ctrl+K on Windows) and choose **Open debug mode**.

To find a test call from the flow builder, open the editor header's menu and choose **Calls**: the Conversation log opens with that agent's calls. Test calls are saved with the agent's other calls (see [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md)).

The back arrow at the top left takes you back to the call in the Conversation log, with the list as you left it.

## A tour of the screen

![Debug mode for an Order Support Flow call: the Share delivery update step in focus on the canvas, its details below, the recording player at the bottom and the Conversation tab on the right](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-screen-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=9f0dbd8de327d6acde39a5a1fc586f75)

The screen has two halves. On the left, the replay: the flow, the details of the current step, and the playback controls. On the right, the call panel with three tabs: **Conversation**, **Visits** and **Logs**. Drag the line between them to resize the panel, or use the button at the top right to hide and show it. On a narrow screen, the panel opens from a **Conversation** button instead.

### The top bar

| Control | What it does |
| - | - |
| Heading | "Debug mode · " and the agent's name. |
| Flow label | Which flow the replay shows (see below). Click it to open that version in the editor, read only. |
| **Visit** | The visit you're on, as "number. step type, step name", and the number of visits. Open it to jump to any visit. Conversation steps have a speech bubble icon. |
| **Copy link** | Copies a link to the call at the current moment of the recording. Whoever opens it lands on the same moment. |

![The Visit menu open, listing the call's seven visits from 1. Greeting to 7. Goodbye, each with its step type](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-visit-picker-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=6cbc98b268106c1ca5da1105c28742dd)

### Which flow you see

Debug mode shows the flow as it was when the call ran, not the flow as it is today. The label beside the heading says which:

| Label | What you see |
| - | - |
| The version and environment, for example "v7 · prod" | The flow as that version has it: the version that answered the call. If an [A/B test](https://docs.tryhamsa.com/agents/release/ab-tests.md) chose it, the tooltip says so. |
| **Draft** | The draft as it was when a test call ran on it. |
| **As it ran** | The flow as it was when the call ran, for a call with no version. |
| **Today's flow** | The call kept no copy of its flow, or its version wouldn't load, so this is the flow as it is now. It may have changed since the call. |

### The canvas

The flow keeps the layout you built in the [flow builder](https://docs.tryhamsa.com/agents/flow/flow-builder.md). During playback:

* The step being heard is in focus, and the view moves to keep it in the middle. The rest of the flow fades back.
* The path the call took so far is drawn, and the transition that fired out of the current step is animated in lime.
* Jumps into a [global step](https://docs.tryhamsa.com/agents/flow/global-steps.md) and back are drawn as dashed, named lines.
* Steps the call visited have a check mark. Steps with problems have a red or amber badge with the number of problems.

Click a step the call reached to go to its next visit; click again to walk through its later visits. Drag to move around, and use the zoom buttons at the bottom left.

The canvas shows every step on its own: the groups you made in the flow builder aren't drawn here.&#x20;

### The current step's details

Under the canvas, three columns describe the visit you're on. Drag the handle above them to give the canvas more room, or click **Hide details** in the footer to fold them away.

| Column | What it shows |
| - | - |
| Variables | **Available on enter (N)**: every variable and its value when the step began. **Extracted at this step (N)**: what the step set. Click a row to see the full value. |
| What the step did | The prompt (see [What the model saw](#check-what-the-model-saw-at-a-step)), **Settings changed here** for a [Change settings step](https://docs.tryhamsa.com/agents/flow/steps/change-settings.md), the tool's **API call**, the **Transfer**, **Transition fired** and where it led, and **Discussion at this step (N)**: each thing the agent said, with its reply time, and the caller's answer. |
| Problems and safety | **Problems (N)**, **Guardrails (N)** and **Policies in the prompt (N)** at this step. |

### Playback

The footer shows the current step's type, name and any problems, then the controls. Playback always runs left to right, in Arabic too.

| Control | What it does |
| - | - |
| **Previous conversation step** and **Next conversation step** | Skip to the previous or next visit to a [Conversation step](https://docs.tryhamsa.com/agents/flow/steps/conversation.md) (or a Start step in conversation mode). |
| **Previous step** and **Next step** | Go one visit back or forward. |
| Play, the waveform and the time | Play the recording. Hover the waveform to see a time; click or drag to move. |
| Problem markers | Errors and warnings from the logs sit under the waveform. Click one to jump there, open its visit and its log. Close ones group into one marker: pick one from the list. |
| Speed (**Playback speed**) | 0.5×, 0.75×, 1× (**Normal**), 1.25×, 1.5× or 2×. |
| **More** | **Download recording**, and **Keyboard shortcuts**. |

Everything moves together: as the recording plays, the canvas, the current visit, the transcript and the logs follow it. Choosing a visit from the **Visit** menu or with the previous and next buttons pauses the recording at the start of that visit. Clicking a visit card or a line of the transcript moves the recording there, and it keeps playing if it was. **Play from here** on a log plays from that moment.

The recording is uploaded after the call ends. Until it arrives, the footer says **Preparing the recording** ("Usually ready a minute or two after the call ends.") and you can step through the call without it: **Play** moves through the visits one by one, and **Restart** starts again from the first. **Check now** looks for the recording at once. If no recording has arrived 15 minutes after the call ended, the footer says **No recording for this call**, with **Check again**. Chat calls have no recording.

## The Conversation tab

The transcript, with the agent's lines on the left and the caller's on the right, each with its time into the call. The line being heard is outlined. Click a line to move the recording to it. Under each agent line, a bar shows how long the reply took and where the time went.

Above the transcript:

* **Reply time** and **Token usage** for the whole call (see [Reference](#how-reply-time-is-measured)). Click a panel's header to fold it; your choice is remembered on this device.
* **Call summary**, when the call's outcome has one.

| Control | What it does |
| - | - |
| **Find in conversation** | Marks every match and shows "2 of 5". Press Enter for the next match and Shift+Enter for the previous, or use **Previous match** and **Next match**. Esc clears it. |
| Speaker | Shows **All** lines, or only the **Agent**'s or the **Caller**'s (and **Moderator** when someone sent an instruction to the agent during the call). |
| Text size | Makes the transcript text larger or smaller. |
| **Export conversation** | **Copy with timestamps**, **Download as .txt**, **Download as .srt**, **Download as .vtt** or **Download as .json**. Exports always take the whole conversation, whatever the search and the speaker filter show. |

![The Conversation tab with driver typed in Find in conversation: two matches, the current one outlined](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-find-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=8bd286b5553fee317b042899a5830b5e)

## The Visits tab

One card per visit: every time the call entered a step. The tab's label shows the number of visits, with a red or amber dot when a visit has an error or a warning. At the top, a summary counts the call's errors, warnings and notes, or says **No problems found**.

![The Visits tab: No problems found at the top, a card per visit, the Order status router folded as one processing step, and the Share delivery update visit open and outlined as the current one](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-visits-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=6e722f03344e02960b8eaa924d59bffc)

A visit gets its own card when the agent spoke there, the caller spoke there, or it had a problem. Runs of quiet steps in between (a tool that ran without a message, a router, a Set variables step) fold into one row, "N processing steps", with their names. Click the row to see them.

**A card's header** shows the step's type icon, its name, when the call reached it, and its number of problems. Below: the step type, the transition the call arrived by (hover for which visit it came from), and how long the call stayed there. A folded card shows the last line said there.

**Open a card** to see:

* Its problems, each with what happened (see [Problems](#problems)).
* What was said there, with each agent reply's time. Slow replies (over 1.5 seconds) are amber.
* **Settings changed here**, for a Change settings step: the voice, the language, or the **New system prompt**.
* The prompt: **Rendered prompt**, **Processing message** or **Original prompt (template)**. **View full** shows all of it.
* The tool's **API call** and the call **Transfer**, when the step had them.
* **Extracts**: each variable the step extracts. Green shows the value; amber "(missing)" means a required variable wasn't extracted. Hover a chip for the value and the extraction prompt; click it for the full value.
* **Transitions**: the one that fired, checked and highlighted, and any that lead nowhere. "N other transitions" shows the rest, global ones included.

Cards with problems start open. The current visit opens while it plays and folds again after, unless you opened it yourself. Click a card to make it the current visit and move the recording there.

![The Verify the order visit card opened: the agent's question with its reply time, the caller's answer, the rendered prompt, and the transition that fired, with one other transition folded](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-visit-card-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=ff36087bca6f081bdc7065213f87a00e)

## The Logs tab

Every event the call logged, in order, with a summary of the call above them: turns (agent and caller), steps, variables, average reply, tools (and how many failed), average tool time, routes, transfers, errors and warnings.

![The Logs tab with the call summary, the search box and the filter chips, Conversation turned off, and the events of the Look up order visit](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-logs-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=5fc5528fd05a8da83ceb7b8480714dfb)

| Control | What it does |
| - | - |
| **Search events…** | Shows only events that contain the text. The count reads "N of M events" with what you searched for. |
| Filter chips | One per kind of event the call has, with its count. All start on; click one to hide that kind. **Reset** turns them all back on and clears the search and the node filter. |
| **Node filter** | Shown when the logs are filtered to one step (on a live call, by clicking the step on the canvas). **Clear node filter** removes it. |
| **Play from here** | Plays the recording from the event's moment, on its visit. |
| **Show the step on the flow** | Moves the canvas to the event's step. |
| Click an event | Opens its details, including the full logged data. |

Events that happen in a row at the same step are grouped into one card with a short summary; click it to see them. Errors and warnings have a red or amber icon. As the recording plays, the list scrolls to the event at the current moment.

The kinds of events:

| Filter | What it covers |
| - | - |
| **Conversation** | What the agent and the caller said. |
| **Flow** | Moves between steps, transitions, router decisions, keypad input, confirmations and the end of the call. |
| **Variables** | Values set by tools, extracted by the model, or set by a Set variables step. |
| **Tools and knowledge** | API tools, web tools and knowledge base lookups. |
| **Transfers** | Call transfers and agent transfers. |
| **Settings** | Changes made by a Change settings step. |
| **System** | Everything else, including guardrail checks and the policies added to the prompt. |

## Find why a call took a wrong turn

**1. Find the step where it went wrong**

Open the **Visits** tab and read down the cards, or press **Next conversation step** to hop between the steps where the agent and the caller talked. Cards with problems are already open.

**2. Check the transition that fired**

Under the canvas, **Transition fired** shows the condition and the step it led to. On the visit card, **Transitions** shows the one that fired and "N other transitions" lists the ones that didn't.

**3. Check the variables**

**Available on enter** shows the values the step had to work with. A wrong or missing value there often explains an Equation transition or a router taking the wrong path.

**4. Read what the caller said**

**Discussion at this step** shows the exchange the model judged the transition on.

Which [Prompt transition](https://docs.tryhamsa.com/agents/flow/transitions.md) fired is worked out from the step the call went to next. When several transitions lead to the same step, the transition is marked "One of several" and the note says which one matched isn't logged.

## Check what the model saw at a step

Go to the visit and look at the prompt in the step details or on its visit card. Its heading says which text you're reading:

| Heading | What it is |
| - | - |
| **Rendered prompt** | The message the step actually played on this call, with [variables](https://docs.tryhamsa.com/agents/variables/overview.md) filled in. |
| **Processing message** | The step played no message, only its processing message (for example "One moment while I check your order."). |
| **Original prompt (template)** | The message as you wrote it in the step, shown when the call logged no played text for this step. |

Then check **Policies in the prompt (N)** in the third column: the policies added to the model's prompt at this step. Each says "Every turn" (added on every turn) or "Matched" with a score (added because the caller's words matched it). **Guardrail** marks a guardrail's instructions. "Left out, over the prompt's limit" lists policies that matched but didn't fit. See [Policies and guardrails](https://docs.tryhamsa.com/agents/safety/policies-and-guardrails.md).

**Guardrails (N)** lists the guardrails checked at the step, the tripped ones first:

| What it says | Meaning |
| - | - |
| **Passed**, "Passed all N checks" | The guardrail was checked and didn't trip. |
| **Tripped**, "Tripped N of M times" | The guardrail tripped. A line below says what it did: "Said its message instead", "Ended the call", "Replaced the text", "Set \<variables>", "Ran its action" or "Recorded only". |
| **Monitoring** | The guardrail only records; it doesn't act. |
| "Not checked in time (N)" | The check didn't finish in time. |
| "The check failed (N)" | The check itself failed. "Its action failed" means its action did. |
| Agent or Caller | Which side's words were checked. |

![The details of the Verify the order visit: the order\_id and phone\_number extracted there, the rendered prompt, the transition that fired to Look up order, three guardrails that passed and the policies in the prompt, one left out over the limit](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-step-details-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=b42b9ee4ae9fcc2bd7d258472128a2df)

## Check a tool call

**1. Go to the tool's visit**

Choose the [Tool step](https://docs.tryhamsa.com/agents/flow/steps/api-request.md) from the **Visit** menu, or click its card on the **Visits** tab.

**2. Read the API call card**

It shows the method, the address that was called, and the result: **OK**, **Failed**, or **Ran** when no result was logged.

**3. Open the request and the response**

**Request** shows what was sent, **Response** what came back. **Arguments** shows the values the tool was given when no request was logged.

![The API request window for the lookup\_order call: the GET method, the order address, and the Authorization header shown as redacted](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-tool-request-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=d5e251356552a0d57f1b0fb8fad9bcac)

**4. Check what it set**

**Extracted at this step** lists the variables the tool's response set, and the next visit's **Available on enter** shows them in use.

Headers that look like credentials (authorization, API keys, tokens, secrets, cookies, passwords) show as `[redacted]`.

When the tool failed, the visit has a **Tool failed** problem with the error, and **Response** opens the error the API returned.

![Debug mode on a call whose Look up order step failed: a Tool failed problem with a gateway timeout on the canvas, in the step details and on the visit card](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-tool-failed-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=074b0836d86732694493e580d4e85a80)

## Find slow replies

**1. Read the Reply time panel**

At the top of the **Conversation** tab: the typical reply, "90% within" a time, and how many replies were slow (over 1.5 seconds).

![The Reply time panel: the typical reply time, 90% within, two slow replies, the split into listening, model and speech, and a bar for each reply](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-reply-time-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=f6329931905409a3fba838092e3084c7)

**2. Go to the slowest reply**

Click **Slowest**, or click a bar in **Each reply**. The transcript and the recording go to that reply.

**3. See where the time went**

The bar under the reply splits it into stages. A long **Model, first token** points at the model or a long prompt; check **Token usage** for the turn's input. A long **Settle wait** or **Turn timeout** means the agent waited to be sure the caller had finished.

## Follow a live call

Open a call that's still in progress and click **Debug mode** (its tooltip says "Follow this call on its flow, step by step, as it happens."). The heading reads "Live call" and the agent's name, and the footer says "The replay is ready when the call ends. Until then the flow follows the call live."

![Debug mode on a live call: the flow following the call at the Look up order step, and the Visits tab listing the three visits so far](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-live-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=6a4625b3e62fde54f103e35155be7bd8)

* Debug mode joins the call as a listener, so you hear it. A speaker button at the top right mutes and unmutes it. The caller doesn't hear you. To speak or send instructions, use [Live calls](https://docs.tryhamsa.com/agents/monitor/live-calls.md).
* The canvas moves to each step as the call reaches it. Click a step to filter the **Logs** to it.
* The **Visits** tab adds a card as the call moves through the flow, with the variables each step sets.
* The **Conversation** tab adds lines as they're said. Search, the speaker filter, exports, **Reply time** and **Token usage** come once the call ends.
* The **Logs** tab adds events as they happen and stays at the newest. Scroll up to read, then click **Jump to latest** to follow again.

When the call ends, a banner says "The call ended. The recording and the replay will be ready shortly." and debug mode loads the finished call.

## Reference

### Problems

Debug mode checks each visit and reports what it finds. Errors are red, warnings amber, notes grey.

| Problem | Level | What it means |
| - | - | - |
| **Tool failed** | Error | The step's tool call failed. The error is shown, and **Response** opens what the API returned. |
| **Prompt did not render** | Error | The text played still holds template code (`{{ }}` or `{% %}`): the variables in it didn't resolve. See [Jinja](https://docs.tryhamsa.com/agents/variables/jinja.md). |
| **Empty message** | Error | A message played at the step, but its text was empty. |
| **Caller spoke while the agent was busy** | Warning | The caller spoke while the flow was working and not waiting for them (this speech is usually ignored), or at a step that played no message. |
| **Variable not extracted** | Warning | A required variable that the flow uses later wasn't extracted when the call left the step. |
| **Variable came back empty** | Warning | The same, but the value came back blank. |
| **Transition leads nowhere** | Warning | One of the step's transitions isn't connected to any step. |
| **Agent spoke at a step with no message** | Note | The agent spoke at a step that has no message or processing message. |

A required variable only counts when the flow reads it somewhere, and the transition that fired can switch it off for its path. The last visit of the call isn't checked for extraction, because the call never left it.

### How reply time is measured

Reply time is measured on voice calls, from the timings the call records for each agent reply. It runs from the caller finishing to the agent starting to speak. The greeting has no reply time.

| Stage | Part | What it is |
| - | - | - |
| Silence | Listening | The pause the agent waits for before treating the caller as finished. |
| Speech to text | Listening | Turning the caller's last words into text. |
| Numbers wait | Listening | Extra time allowed when the caller was saying a number. |
| Settle wait or Turn timeout | Listening | Waiting to be sure the turn ended: "End of turn detected", or "End of turn timed out". |
| Model, first token and Model, first chunk | Model | The model starting its answer. |
| Speech | Speech | The voice producing the first audio. |

The model can start while the agent is still waiting to be sure the turn ended. That overlap is counted once, so a reply's time can be less than its stages added up.

In the **Reply time** panel, the typical reply is the median, "90% within" is the time nine replies in ten beat, and a reply is slow when it takes over 1.5 seconds. **Listening**, **Model** and **Speech** show the average of each part. Drag across **Each reply** to zoom in on some replies; Escape or **Show all** zooms back out.

### How token usage is counted

**Token usage** adds up the tokens the agent's model reported for each reply on the call. It doesn't include any other model, and it shows tokens only, not cost.

| Figure | What it is |
| - | - |
| Total | All tokens over the call's model turns. |
| **Fresh input**, **Cached input**, **Output** | Input tokens the model read fresh, input it read from the provider's cache, and the tokens it wrote. |
| **Cache hit rate** | The share of input read from the cache. |
| Averages | The average input and output per reply. |
| **Input per reply** | The input of each reply, to see the prompt grow over the call. Click a bar to go to that reply. |
| **Longest prompt** | The most input one reply sent. Click it to go to that reply. |

![The Token usage panel: the call's total tokens, the split into fresh input, cached input and output, the cache hit rate, and the input per reply chart](https://mintcdn.com/hamsa-452fa79a/2654KIaxnTY04VOj/images/agents/monitor/debug-mode-token-usage-light.webp?fit=max\&auto=format\&n=2654KIaxnTY04VOj\&q=85\&s=7c5ba452a3359a40b4ef989084837edf)

### Keyboard shortcuts

These work anywhere in debug mode while a recording is loaded, except while you type in a field or have a menu open. Press `?` to see every shortcut.

| Keys | What they do |
| - | - |
| Space or K | Play or pause. On a focused button Space presses it, and on the canvas it pans; K always plays. |
| J or L | Back or forward 10 seconds. |
| Left arrow or Right arrow | Back or forward 5 seconds. |
| Shift+, or Shift+. | Slower or faster. |

With debug mode open, the command menu (Cmd+K on Mac, Ctrl+K on Windows) also has "Play or pause the recording" and the playback speeds.

## Good to know

* A link with `?t=` at the end opens the call at that moment: seconds (`?t=95`), or minutes and seconds (`?t=1:35`). As the recording plays, the address bar keeps the current moment, so the link you copy from it lands there too.
* If a call's logs don't show it moving between steps, debug mode shows the flow with "The logs of this call do not show it moving through the flow." and the **Visits** tab says **No visits logged**.
* When some lines of the transcript can't be placed on a step, the end of the **Visits** tab says how many.
* Personal details a guardrail encoded on the call show as **Hidden** until you enter the key. See [Protect personal data](https://docs.tryhamsa.com/agents/safety/personal-data.md).
* Changing the flow after a call doesn't change its replay: debug mode shows the flow as the call ran it, unless the label says **Today's flow**.

## Related

> [card] [Call details](https://docs.tryhamsa.com/agents/monitor/call-details.md)
>
> The transcript, recording, analysis and logs of any call.

> [card] [Transitions](https://docs.tryhamsa.com/agents/flow/transitions.md)
>
> How a flow moves from one step to the next.

> [card] [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md)
>
> Make test calls, then replay them here.

> [card] [Policies and guardrails](https://docs.tryhamsa.com/agents/safety/policies-and-guardrails.md)
>
> What the guardrails and policies at each step are.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.