Skip to main content
The Debugging Agent provides systematic bug diagnosis and resolution. It follows an 8-step debugging methodology for complex issues and adapts its approach based on whether you have a bug to fix or a question to answer. Debugging Agent

8-Step Methodology

Structured bug diagnosis

17 Tools

Knowledge graph & code analysis

​
API Overview

Endpoint: POST /api/v1/agents/debug Authentication: Bearer token required
Request:
{
  query: string              // Bug report or code question
  project_id: string         // Project identifier
  conversation_id: string    // Conversation context
  node_ids?: string[]        // Optional: Specific code references
}
Response:
{
  response: string           // Markdown-formatted analysis or answer
  tool_calls: ToolCall[]     // Tools used during investigation
  sources: string[]          // Files and line numbers referenced
}

​
How It Works

The agent enriches context before processing. It fetches code from referenced node IDs to understand the bug location. For simple queries, it processes them directly using its tools. For complex bugs, it delegates to specialized sub-agents with up to 12 iterations each. Debugging Agent Chat

​
Debugging Methodology

The agent follows an 8-step structured methodology for bug diagnosis.

​
Example

curl -X POST https://production-api.potpie.ai/api/v1/agents/debug \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Users are getting null pointer errors during checkout when they have empty shopping carts",
    "project_id": "proj_123",
    "conversation_id": "conv_456"
  }'

{
  "response": "## Root Cause Analysis\n\n### Step 1: Problem Understanding\n\nThe null pointer error occurs when checkout attempts to access cart items without verifying the cart exists and has items.\n\n### Step 3: Root Cause Identified\n\nThe issue originates in `app/services/checkout_service.py:67`.\n\n### Step 4: Generalized Issue\n\nThis is a broader pattern of missing null/empty checks before accessing collections. Found 3 similar issues.\n\n### Step 5: Solution Design\n\nAdd validation before processing. Return early with clear error message for empty carts.",
  "sources": [
    "app/services/checkout_service.py:67",
    "app/services/order_service.py:89",
    "app/services/address_service.py:34"
  ]
}

​
Error Responses

The request has invalid format or missing required fields.
{
  "error": "VALIDATION_ERROR",
  "message": "Missing required field: project_id"
}
The API key is missing or invalid.
{
  "error": "UNAUTHORIZED",
  "message": "Invalid API key"
}
The specified project does not exist or is not accessible.
{
  "error": "PROJECT_NOT_FOUND",
  "message": "Project not found"
}
You have exceeded the rate limit.
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Retry after 60 seconds"
}