Depuração do Comportamento de Agentes

Intermediário⏱45 min📖3 min de leituraLição 3 de 6

Depuração do Comportamento de Agentes

Diagnostique e corrija problemas com agentes do OpenCode. Aprenda técnicas de depuração, análise de logs e como rastrear o ciclo de vida de requisições para identificar problemas.

Modo de Depuração

Ative o modo de depuração para ver informações detalhadas:

bash

opencode --debug

Ou defina a variável de ambiente:

bash

export OPENCODE_DEBUG=1
opencode

O que o Modo de Depuração Mostra

Ciclo de Vida da Requisição

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

Invocações de Ferramentas

[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

Verificações de Permissão

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

Problemas Comuns e Soluções

Problema: Agente Não Responde

Sintomas:

Sem resposta após enviar uma mensagem
Longos atrasos sem saída

Passos de Depuração:

Verifique a validade da chave de API:

bash

echo $OPENAI_API_KEY | head -c 10

Verifique a conectividade de rede:

bash

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

Verifique os logs de depuração para erros de timeout

Solução:

json

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

Problema: Agente Errado Selecionado

Sintomas:

Requisição vai para o agente errado
Agente não entende a tarefa

Passos de Depuração:

Verifique as descrições dos agentes na saída de depuração
Revise as regras de roteamento
Teste a correspondência de padrões

Solução:

json

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

Problema: Permissão Negada

Sintomas:

Erros "Permission denied"
Ferramentas não executando

Passos de Depuração:

Verifique as regras de permissão na saída de depuração
Verifique a correspondência de padrões
Revise a ordem de negação vs permissão

Solução:

json

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

Análise de Logs

Níveis de Log

Nível	Saída	Caso de Uso
Padrão	Informações básicas	Operação normal
Depuração	Rastreamentos detalhados	Solução de problemas
Detalhado	Conteúdo completo	Depuração profunda

Ativando o Modo Detalhado

bash

opencode --verbose

Ou na sessão interativa:

> /verbose

Rastreamento de Requisições

Rastreamento Manual

Siga esta lista de verificação para depuração manual:

Verifique a configuração:

bash

cat opencode.json | jq .

Verifique a chave de API:

bash

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

Teste a API diretamente:

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

Verifique a saída de depuração:

bash

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

Depuração de Performance

Respostas Lentas

Causas:

Janela de contexto grande
Prompts complexos
Latência de rede
Limite de taxa

Soluções:

Causa	Solução
Contexto grande	Limpe a conversa com `/clear`
Prompts complexos	Simplifique as instruções
Latência de rede	Verifique a conexão, use uma região mais próxima
Limite de taxa	Adicione atrasos, atualize o plano da API

Uso de Tokens

Monitore o uso de tokens na saída de depuração:

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