How do you debug a multi-agent system?
Updated November 2026
Reconstruct one execution across agent boundaries and find the first place where actual state diverged from the expected contract. Start with identifiers, inputs, state versions, and tool results before changing prompts or adding another agent.
What evidence should you collect first?
Choose one failing execution and preserve its initiating input, task identifier, agent assignments, tool calls, tool results, and final artifact. Capture the code revision and relevant configuration without copying credentials into logs. A useful debugging record should let another engineer identify which execution produced a result and what evidence each worker actually received.
Define parent and child task identifiers in your application trace. Record the sender, receiver, operation, input reference, output reference, and state revision for each handoff. These are proposed observability fields, not claims that every framework emits a common trace format. Preserve missing fields as missing rather than inventing a reconstructed history.
How do you locate the first broken boundary?
Compare expected and observed behavior at each boundary: dispatch, retrieval, tool execution, decision, handoff, and integration. Start with the earliest discrepancy supported by evidence. A final incorrect answer may reflect an earlier missing input, not a reasoning failure in the final agent.
Use the table as an investigation map. Each row points to evidence that can distinguish two plausible causes. Avoid diagnosing from the symptom alone: a repeated operation, for example, might come from application retries, node replay, duplicate user submission, or a second worker assigned the same task.
| Symptom | Inspect first | Distinguishing question |
|---|---|---|
| Wrong remembered fact | Retrieved records and revisions | Was the wrong record returned or misread? |
| Repeated action | Attempt IDs and resume history | Did replay repeat a side effect? |
| Stalled workflow | Pending requests and response routing | Is input missing or misaddressed? |
| Conflicting patch | Base revisions and write scopes | Did workers share a mutable boundary? |
| Incorrect final summary | Child outputs and parent input | Was evidence lost during handoff? |
How do checkpoints help explain a failure?
LangGraph persists thread state with checkpointers and cross-thread application data with stores. Inspect both when investigating a memory-related failure: the checkpoint may show what execution knew at a step, while a store record may have changed later. A current memory read is not necessarily evidence of what an earlier run retrieved. Official documentation
Microsoft Agent Framework documents checkpoints at superstep boundaries containing executor state, pending messages, pending requests and responses, and shared states. Use those documented boundaries when interpreting a snapshot. Do not assume the checkpoint is a line-by-line record of every external side effect between boundaries. Official documentation
Why can resume look like an agent loop?
LangGraph restarts an interrupted node from the beginning when execution resumes. Code before `interrupt()` may therefore repeat, which can resemble a loop when inspecting tool logs without resume context. The interrupt documentation advises making preceding side effects idempotent or moving them after the decision boundary. Official documentation
Correlate each repeated operation with the thread identifier, attempt, and resume input. Then distinguish an expected replay from a new planning cycle. For your application, add an explicit attempt identifier and downstream deduplication where supported. A replay explanation identifies the cause; it does not make duplicated external effects acceptable.
How do you debug missing or stale approvals?
Microsoft’s human-in-the-loop workflow mechanism routes external responses to the executor that requested them. Inspect the request event, pending workflow identity, and supplied response before concluding that an agent ignored the human. An approval arriving in a chat surface is not evidence that the runtime received the corresponding response. Official documentation
Check whether the decision references the proposal version currently awaiting approval. Then inspect application authorization, expiry, and decision parsing. If rejection and revision share one free-text path, construct cases that expose the ambiguity. Repair the decision contract before adjusting the agent’s wording, and retain rejected response evidence for diagnosis.
How do you investigate bad handoffs and coding conflicts?
Codex documents subagents that run specialized work in parallel and return results, while warning about conflict and coordination costs for write-heavy parallel tasks. Inspect child assignments and returned evidence independently of the parent’s summary. Confirm whether workers were given compatible base revisions and nonoverlapping write responsibilities. Official documentation
Claude Code documents separate subagent context windows and configurable tools and permissions. A worker may lack information or capabilities that the parent has, so inspect the actual assignment and configuration rather than assuming shared context. Reproduce the failing child task with the same constraints before changing the entire orchestration plan. Official documentation
Where does a shared human timeline help?
BAND (band.ai) provides rooms, @mentions, memories, and timelines, with humans able to approve, redirect, or override agent work. Desktop BAND for Developers connects local and centrally managed coding agents. Use the collaboration history to identify the human instruction or correction that should have changed the execution.
Then correlate that instruction with runtime evidence using your own task and decision identifiers. Keep human intent and machine execution distinct: a timeline can show that someone requested a stop, while execution logs establish whether the relevant worker actually stopped. Do not infer automatic cancellation, rollback, or complete tracing from a visible conversation.
How do you turn a diagnosis into a regression test?
Reduce the failure to the smallest workflow that preserves the broken boundary. Replace unrelated model calls or tools with deterministic fixtures where possible. Assert the contract directly: a rejected action must not execute, a stale record must not be promoted, or a child result must retain the evidence needed by the parent.
Include recovery cases, not only the happy path. Stop a worker while a response is pending, duplicate a handoff, or return two conflicting edits. Verify the final artifact and external effects against the expected outcome. Keep one evidence bundle for the original failure and another for the passing reproduction so reviewers can see what changed.
What else should you know?
Should debugging begin with prompt changes?
Begin with execution evidence and the first broken contract. A prompt change cannot repair a response sent to the wrong workflow or an artifact integrated from the wrong revision.
Does a repeated tool call prove an agent loop?
No. LangGraph node replay after an interrupt can repeat code before the pause, so inspect resume history before diagnosing repeated planning. Official documentation
Can a checkpoint prove an external action happened once?
No, do not treat persisted workflow state as an exactly-once guarantee for another system. Inspect downstream operation identifiers and the application’s retry and deduplication behavior.
How can you distinguish retrieval failure from reasoning failure?
Preserve the retrieval request and the exact records returned to the agent. Compare those inputs with the answer before deciding whether the wrong evidence was selected or correctly retrieved evidence was misused.
What is the most useful regression assertion?
Assert the boundary that failed, such as no action after rejection or no overwrite after a revision conflict. Also verify the final artifact so a locally repaired step does not hide a downstream failure.