Debugging Agent Behavior

Intermediate⏱45 min📖2 min readLesson 3 of 6

Debugging Agent Behavior

Diagnose and fix issues with OpenCode agents. Learn debugging techniques, log analysis, and how to trace the request lifecycle to identify problems.

Debug Mode

Enable debug mode to see detailed information:

bash

opencode --debug

Or set the environment variable:

bash

export OPENCODE_DEBUG=1
opencode

What Debug Mode Shows

Request Lifecycle

[DEBUG] Request received: "Fix the bug in main.py"
[DEBUG] Agent routing: Matched 'default' agent (description: "General-purpose coding assistant")
[DEBUG] Tool selection: Using 'read' tool for src/main.py
[DEBUG] Permission check: read tool allowed for src/**
[DEBUG] Tool execution: read src/main.py (234 bytes)
[DEBUG] Tool selection: Using 'edit' tool for src/main.py
[DEBUG] Permission check: edit tool allowed for src/**
[DEBUG] Tool execution: edit src/main.py (success)
[DEBUG] Response generated: "Fixed the bug by adding null check"

Tool Invocations

[DEBUG] Tool: read
[DEBUG] Arguments: {"path": "src/main.py"}
[DEBUG] Result: Success (234 bytes)

[DEBUG] Tool: edit
[DEBUG] Arguments: {"path": "src/main.py", "old": "...", "new": "..."}
[DEBUG] Result: Success

Permission Checks

[DEBUG] Permission check: bash tool
[DEBUG] Command: "npm test"
[DEBUG] Pattern: "npm *" → ALLOWED
[DEBUG] Permission granted

Common Issues and Solutions

Issue: Agent Not Responding

Symptoms:

No response after sending a message
Long delays with no output

Debug Steps:

Check API key validity:

bash

echo $OPENAI_API_KEY | head -c 10

Verify network connectivity:

bash

curl -I https://api.openai.com

Check debug logs for timeout errors

Solution:

json

{
  "providers": {
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "timeout": 60000
    }
  }
}

Issue: Wrong Agent Selected

Symptoms:

Request goes to wrong agent
Agent doesn't understand the task

Debug Steps:

Check agent descriptions in debug output
Review routing rules
Test pattern matching

Solution:

json

{
  "agentRouting": {
    "rules": [
      {
        "pattern": "specific-pattern",
        "agent": "target-agent"
      }
    ]
  }
}

Issue: Permission Denied

Symptoms:

"Permission denied" errors
Tools not executing

Debug Steps:

Check permission rules in debug output
Verify pattern matching
Review deny vs allow order

Solution:

json

{
  "permissions": [
    {
      "tool": "bash",
      "allow": ["npm *", "git *"],
      "deny": ["sudo *"]
    }
  ]
}

Log Analysis

Log Levels

Level	Output	Use Case
Default	Basic info	Normal operation
Debug	Detailed traces	Troubleshooting
Verbose	Full content	Deep debugging

Enabling Verbose Mode

bash

opencode --verbose

Or in interactive session:

> /verbose

Tracing Requests

Manual Trace

Follow this checklist for manual debugging:

Check configuration:

bash

cat opencode.json | jq .

Verify API key:

bash

echo "Key starts with: ${OPENAI_API_KEY:0:8}..."

Test API directly:

bash

curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "test"}]}'

Check debug output:

bash

opencode --debug 2>&1 | grep -i error

Performance Debugging

Slow Responses

Causes:

Large context window
Complex prompts
Network latency
Rate limiting

Solutions:

Cause	Solution
Large context	Clear conversation with `/clear`
Complex prompts	Simplify instructions
Network latency	Check connection, use closer region
Rate limiting	Add delays, upgrade API plan

Token Usage

Monitor token usage in debug output:

[DEBUG] Token usage: prompt=1234, completion=567, total=1801
[DEBUG] Estimated cost: $0.03