LangSmith Fetch - Depuração de Agentes

LangSmith Fetch - Habilidade de Depuração de Agentes

Depure agentes LangChain e LangGraph buscando rastros de execução diretamente do LangSmith Studio no seu terminal.

Quando Usar Esta Habilidade

Ative automaticamente quando o usuário mencionar:

• 🐛 "Depurar meu agente" ou "O que deu errado?"
• 🔍 "Mostre-me rastros recentes" ou "O que aconteceu?"
• ❌ "Verifique erros" ou "Por que falhou?"
• 💾 "Analise operações de memória" ou "Verifique LTM"
• 📊 "Revise o desempenho do agente" ou "Verifique uso de tokens"
• 🔧 "Quais ferramentas foram chamadas?" ou "Mostre o fluxo de execução"

Pré-requisitos

1. Instalar langsmith-fetch

pip install langsmith-fetch

2. Configurar Variáveis de Ambiente

export LANGSMITH_API_KEY="sua_chave_langsmith_api"
export LANGSMITH_PROJECT="nome_do_seu_projeto"

Verificar configuração:

echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

Fluxos de Trabalho Principais

Fluxo de Trabalho 1: Depuração Rápida de Atividade Recente

Quando o usuário perguntar: "O que acabou de acontecer?" ou "Depurar meu agente"

Executar:

langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty

Analisar e reportar:

1. ✅ Número de rastros encontrados
2. ⚠️ Erros ou falhas
3. 🛠️ Ferramentas que foram chamadas
4. ⏱️ Tempos de execução
5. 💰 Uso de tokens

Exemplo de formato de resposta:

Encontrados 3 rastros nos últimos 5 minutos:

Rastro 1: ✅ Sucesso
- Agente: memento
- Ferramentas: recall_memories, create_entities
- Duração: 2.3s
- Tokens: 1.245

Rastro 2: ❌ Erro
- Agente: cypher
- Erro: "Neo4j connection timeout"
- Duração: 15.1s
- Falhou em: ferramenta search_nodes

Rastro 3: ✅ Sucesso
- Agente: memento
- Ferramentas: store_memory
- Duração: 1.8s
- Tokens: 892

💡 Problema encontrado: Rastro 2 falhou devido a timeout do Neo4j. Recomenda-se verificar a conexão do banco de dados.

---

Fluxo de Trabalho 2: Análise Profunda de Rastro Específico

Quando o usuário fornecer: ID do rastro ou disser "investigue esse erro"

Executar:

langsmith-fetch trace <trace-id> --format json

Analisar JSON e reportar:

1. 🎯 O que o agente estava tentando fazer
2. 🛠️ Quais ferramentas foram chamadas (em ordem)
3. ✅ Resultados das ferramentas (sucesso/falha)
4. ❌ Mensagens de erro (se houver)
5. 💡 Análise de causa raiz
6. 🔧 Correção sugerida

Exemplo de formato de resposta:

Análise Profunda - Rastro abc123

Objetivo: Usuário perguntou "Encontre todos os projetos no Neo4j"

Fluxo de Execução:
1. ✅ search_nodes(query: "projects")
   → Encontrados 24 nós

2. ❌ get_node_details(node_id: "proj_123")
   → Erro: "Node not found"
   → Este é o ponto de falha

3. ⏹️ Execução interrompida

Causa Raiz:
A ferramenta search_nodes retornou IDs de nós que não existem mais no banco de dados,
possivelmente devido a exclusões recentes.

Correção Sugerida:
1. Adicionar tratamento de erro na ferramenta get_node_details
2. Filtrar nós excluídos nos resultados da pesquisa
3. Atualizar estratégia de invalidação de cache

Uso de Tokens: 1.842 tokens ($0,0276)
Tempo de Execução: 8,7 segundos

---

Fluxo de Trabalho 3: Exportar Sessão de Depuração

Quando o usuário disser: "Salvar esta sessão" ou "Exportar rastros"

Executar:

# Criar pasta de sessão com timestamp
SESSION_DIR="langsmith-debug/session-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$SESSION_DIR"

# Exportar rastros
langsmith-fetch traces "$SESSION_DIR/traces" --last-n-minutes 30 --limit 50 --include-metadata

# Exportar threads (conversas)
langsmith-fetch threads "$SESSION_DIR/threads" --limit 20

Reportar:

✅ Sessão exportada com sucesso!

Localização: langsmith-debug/session-20251224-143022/
- Rastros: 42 arquivos
- Threads: 8 arquivos

Agora você pode:
1. Revisar arquivos de rastro individuais
2. Compartilhar pasta com a equipe
3. Analisar com ferramentas externas
4. Arquivar para referência futura

Tamanho da sessão: 2,3 MB

---

Fluxo de Trabalho 4: Detecção de Erros

Quando o usuário perguntar: "Mostre-me erros" ou "O que está falhando?"

Executar:

# Buscar rastros recentes
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format json > recent-traces.json

# Procurar por erros
grep -i "error\|failed\|exception" recent-traces.json

Analisar e reportar:

1. 📊 Total de erros encontrados
2. ❌ Tipos de erro e frequência
3. 🕐 Quando os erros ocorreram
4. 🎯 Quais agentes/ferramentas falharam
5. 💡 Padrões comuns

Exemplo de formato de resposta:

Análise de Erros - Últimos 30 Minutos

Total de Rastros: 50
Rastros com Falha: 7 (14% de taxa de falha)

Detalhamento de Erros:
1. Neo4j Connection Timeout (4 ocorrências)
   - Agente: cypher
   - Ferramenta: search_nodes
   - Primeira ocorrência: 14:32
   - Última ocorrência: 14:45
   - Padrão: Acontece durante pico de carga

2. Falha no Armazenamento de Memória (2 ocorrências)
   - Agente: memento
   - Ferramenta: store_memory
   - Erro: "Pinecone rate limit exceeded"
   - Ocorreu: 14:38, 14:41

3. Ferramenta Não Encontrada (1 ocorrência)
   - Agente: sqlcrm
   - Ferramenta tentada: "export_report" (não existe)
   - Ocorreu: 14:35

💡 Recomendações:
1. Adicionar lógica de repetição para timeouts do Neo4j
2. Implementar limitação de taxa para Pinecone
3. Corrigir configuração da ferramenta sqlcrm

---

Casos de Uso Comuns

Caso de Uso 1: "Agente Não Está Respondendo"

Usuário diz: "Meu agente não está fazendo nada"

Passos:

1. Verificar se existem rastros:

   langsmith-fetch traces --last-n-minutes 5 --limit 5
   

2. Se NENHUM rastro encontrado:

   • A rastreabilidade pode estar desabilitada
   • Verificar: LANGCHAIN_TRACING_V2=true no ambiente
   • Verificar: LANGCHAIN_API_KEY está configurada
   • Confirmar se o agente realmente executou

3. Se rastros encontrados:

   • Revisar erros
   • Verificar tempo de execução (travado?)
   • Confirmar se as chamadas de ferramentas foram concluídas

---

Caso de Uso 2: "Ferramenta Errada Chamada"

Usuário diz: "Por que ele usou a ferramenta errada?"

Passos:

1. Obter o rastro específico
2. Revisar as ferramentas disponíveis no momento da execução
3. Verificar o raciocínio do agente para seleção da ferramenta
4. Examinar descrições/instruções das ferramentas
5. Sugerir melhorias no prompt ou na configuração das ferramentas

---

Caso de Uso 3: "Memória Não Está Funcionando"

Usuário diz: "O agente não se lembra das coisas"

Passos:

1. Procurar por operações de memória:

   langsmith-fetch traces --last-n-minutes 10 --limit 20 --format raw | grep -i "memory\|recall\|store"
   

2. Verificar:

   • As ferramentas de memória foram chamadas?
   • O recall retornou resultados?
   • As memórias foram realmente armazenadas?
   • As memórias recuperadas estão sendo usadas?

---

Caso de Uso 4: "Problemas de Desempenho"

Usuário diz: "O agente está muito lento"

Passos:

1. Exportar com metadados:

   langsmith-fetch traces ./perf-analysis --last-n-minutes 30 --limit 50 --include-metadata
   

2. Analisar:

   • Tempo de execução por rastro
   • Latências de chamadas de ferramentas
   • Uso de tokens (tamanho do contexto)
   • Número de iterações
   • Operações mais lentas

3. Identificar gargalos e sugerir otimizações

---

Guia de Formatos de Saída

Formato Pretty (Padrão)

langsmith-fetch traces --limit 5 --format pretty

Uso para: Inspeção visual rápida, mostrar para usuários

Formato JSON

langsmith-fetch traces --limit 5 --format json

Uso para: Análise detalhada, revisão com destaque de sintaxe

Formato Raw

langsmith-fetch traces --limit 5 --format raw

Uso para: Encadear com outros comandos, automação

---

Funcionalidades Avançadas

Filtragem Baseada em Tempo

# Após timestamp específico
langsmith-fetch traces --after "2025-12-24T13:00:00Z" --limit 20

# Últimos N minutos (mais comum)
langsmith-fetch traces --last-n-minutes 60 --limit 100

Incluir Metadados

# Obter contexto extra
langsmith-fetch traces --limit 10 --include-metadata

# Metadados incluem: tipo de agente, modelo, tags, ambiente

Busca Concorrente (Mais Rápida)

# Acelerar exportações grandes
langsmith-fetch traces ./output --limit 100 --concurrent 10

---

Solução de Problemas

"Nenhum rastro encontrado com os critérios"

Causas possíveis:

1. Nenhuma atividade do agente no período
2. Rastreabilidade desabilitada
3. Nome do projeto incorreto
4. Problemas com a chave da API

Soluções:

# 1. Tentar período maior
langsmith-fetch traces --last-n-minutes 1440 --limit 50

# 2. Verificar ambiente
echo $LANGSMITH_API_KEY
echo $LANGSMITH_PROJECT

# 3. Tentar buscar threads em vez de rastros
langsmith-fetch threads --limit 10

# 4. Verificar se a rastreabilidade está habilitada no código
# Verifique por: LANGCHAIN_TRACING_V2=true

"Projeto não encontrado"

Solução:

# Visualizar configuração atual
langsmith-fetch config show

# Definir projeto correto
export LANGSMITH_PROJECT="nome-correto-do-projeto"

# Ou configurar permanentemente
langsmith-fetch config set project "nome-do-seu-projeto"

Variáveis de ambiente não persistem

Solução:

# Adicionar ao arquivo de configuração do shell (~/.bashrc ou ~/.zshrc)
echo 'export LANGSMITH_API_KEY="sua_chave"' >> ~/.bashrc
echo 'export LANGSMITH_PROJECT="seu_projeto"' >> ~/.bashrc

# Recarregar configuração do shell
source ~/.bashrc

---

Melhores Práticas

1. Verificações de Saúde Regulares

# Verificação rápida após fazer alterações
langsmith-fetch traces --last-n-minutes 5 --limit 5

2. Armazenamento Organizado

langsmith-debug/
├── sessions/
│   ├── 2025-12-24/
│   └── 2025-12-25/
├── error-cases/
└── performance-tests/

3. Documentar Descobertas

Quando encontrar bugs:

1. Exportar o rastro problemático
2. Salvar na pasta error-cases/
3. Anotar o que deu errado em um README
4. Compartilhar o ID do rastro com a equipe

4. Integração com Desenvolvimento

# Antes de commitar código
langsmith-fetch traces --last-n-minutes 10 --limit 5

# Se erros encontrados
langsmith-fetch trace <error-id> --format json > pre-commit-error.json

---

Referência Rápida

# Comandos mais comuns

# Depuração rápida
langsmith-fetch traces --last-n-minutes 5 --limit 5 --format pretty

# Rastro específico
langsmith-fetch trace <trace-id> --format pretty

# Exportar sessão
langsmith-fetch traces ./debug-session --last-n-minutes 30 --limit 50

# Encontrar erros
langsmith-fetch traces --last-n-minutes 30 --limit 50 --format raw | grep -i error

# Com metadados
langsmith-fetch traces --limit 10 --include-metadata

---

Recursos

• CLI LangSmith Fetch: https://github.com/langchain-ai/langsmith-fetch
• LangSmith Studio: https://smith.langchain.com/
• Documentação LangChain: https://docs.langchain.com/
• Repositório da Habilidade: https://github.com/OthmanAdi/langsmith-fetch-skill

---

Notas para Claude

• Sempre verifique se langsmith-fetch está instalado antes de executar comandos
• Verifique se as variáveis de ambiente estão configuradas
• Use --format pretty para saída legível para humanos
• Use --format json quando precisar analisar dados programaticamente
• Ao exportar sessões, crie estruturas de pastas organizadas
• Sempre forneça análises claras e insights acionáveis
• Se comandos falharem, ajude a solucionar problemas de configuração

---

Versão: 0.1.0 Autor: Ahmad Othman Ammar Adi Licença: MIT Repositório: https://github.com/OthmanAdi/langsmith-fetch-skill