Depuración del Comportamiento de Agentes

Intermedio⏱45 min📖3 min de lecturaLección 3 de 6

Depuración del Comportamiento de Agentes

Diagnostica y corrige problemas con los agentes de OpenCode. Aprende técnicas de depuración, análisis de registros y cómo rastrear el ciclo de vida de las solicitudes para identificar problemas.

Modo de Depuración

Habilita el modo de depuración para ver información detallada:

bash

opencode --debug

O configura la variable de entorno:

bash

export OPENCODE_DEBUG=1
opencode

Qué Muestra el Modo de Depuración

Ciclo de Vida de la Solicitud

[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"

Invocaciones de Herramientas

[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

Verificaciones de Permisos

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

Problemas Comunes y Soluciones

Problema: Agente No Responde

Síntomas:

Sin respuesta después de enviar un mensaje
Largos retardos sin salida

Pasos de Depuración:

Verificar la validez de la clave API:

bash

echo $OPENAI_API_KEY | head -c 10

Verificar la conectividad de red:

bash

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

Revisar registros de depuración para errores de timeout

Solución:

json

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

Problema: Agente Equivocado Seleccionado

Síntomas:

La solicitud va al agente equivocado
El agente no entiende la tarea

Pasos de Depuración:

Revisar descripciones de agentes en la salida de depuración
Revisar reglas de enrutamiento
Probar coincidencia de patrones

Solución:

json

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

Problema: Permiso Denegado

Síntomas:

Errores de "Permiso denegado"
Herramientas no se ejecutan

Pasos de Depuración:

Verificar reglas de permisos en la salida de depuración
Verificar coincidencia de patrones
Revisar el orden de deny vs allow

Solución:

json

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

Análisis de Registros

Niveles de Registro

Nivel	Salida	Caso de Uso
Predeterminado	Información básica	Operación normal
Depuración	Trazas detalladas	Solución de problemas
Detallado	Contenido completo	Depuración profunda

Habilitar Modo Detallado

bash

opencode --verbose

O en sesión interactiva:

> /verbose

Rastreando Solicitudes

Rastreo Manual

Sigue esta lista de verificación para depuración manual:

Verificar configuración:

bash

cat opencode.json | jq .

Verificar clave API:

bash

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

Probar API directamente:

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"}]}'

Verificar salida de depuración:

bash

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

Depuración de Rendimiento

Respuestas Lentas

Causas:

Ventana de contexto grande
Prompts complejos
Latencia de red
Limitación de tasa

Soluciones:

Causa	Solución
Contexto grande	Limpiar conversación con `/clear`
Prompts complejos	Simplificar instrucciones
Latencia de red	Verificar conexión, usar región más cercana
Limitación de tasa	Agregar demoras, actualizar plan de API

Uso de Tokens

Monitorea el uso de tokens en la salida de depuración:

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