Skip to main content
The Debugging Agent traces issues through the knowledge graph from where they surface to where they originate, identifies the root cause, and returns a targeted fix. For a bug report, it runs a structured investigation that follows the issue to its source and systematically evaluates every viable fix location before recommending the most appropriate resolution. If specific nodes are referenced in the query, it fetches their source code and appends it as code context.

​
How It Works

​
Understand the Problem

The agent immediately separates the reported symptom from any suggested fix. The suggested fix are noted and only the observed symptom is carried forward into the investigation. It documents the real problem, the debugging principles it will follow, and the success criteria. It then breaks the investigation into traceable tasks before any navigation begins.

​
Explore and Hypothesize

The agent formulates candidate hypotheses for what could cause the symptom. Each hypothesis is tracked and marked confirmed or eliminated as the investigation progresses. Navigation follows the same broad-to-narrow pattern as the Q&A Agent, moving from finding where relevant functionality lives in the knowledge graph -> understanding directory layout and module organization -> retrieving specific files, functions, and call relationships. It reads files directly by path with optional line ranges, reads multiple files simultaneously when tracing across modules, and searches file contents by pattern to follow state through code paths not fully captured in the graph.

​
Identify Root Cause

The agent traces in both directions from the symptom. Upstream it follows the call chain backward to find where bad state was first introduced. Downstream it identifies what consumes the code’s output and what assumptions those consumers make. Whenever a reported bug represents a broader category rather than a single isolated case, the agent treats it as a pattern, enumerates all sibling instances across the codebase, and evaluates each one to determine whether the same issue is present elsewhere.

​
Generalize

The agent evaluates every candidate fix location before recommending one. Different types of fix locations are :
  • A origin fix prevents bad state from being created. This is always the preferred approach.
  • A transformation fix corrects the issue during normal data processing. This is acceptable.
  • A boundary fix validates inputs at API or module boundaries. This is acceptable.
  • A symptom fix patches the issue where the bug appears rather than where it originates. This should be avoided.
  • A consumer guard adds defensive checks in every consumer. This is considered a red flag.
After this two validation tests are used to confirm the fix is applied at the correct location.
  1. The Spreading Knowledge Test asks whether other parts of the code still need to know about the edge case after the fix. If yes, the fix is too far downstream.
  2. The Future Bug Test asks whether a new caller would automatically benefit from the fix. If no, the fix is too shallow.

​
Design and Implement

The fix targets the origin or transformation point, reusing existing utilities and helpers where they exist. The agent explains the fix with file path and line citations. Before returning, it verifies that the generalized issue, all affected components, and the designed fix are fully addressed.

​
Calling the Agent

curl -X POST http://localhost:8001/api/v2/conversations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_ids": ["proj_abc123"],
    "agent_ids": ["debugging_agent"]
  }'
Once you have a conversation_id, describe the issue: 
curl -X POST http://localhost:8001/api/v2/conversations/conv_xyz789/message/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The auth token resets on every redirect. Happens only on OAuth flows."
  }'

​
Next Steps