langsmith-fetch

LangSmith Fetch - Skill 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 Skill

Ative automaticamente quando o usuário mencionar:

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

Pré-requisitos

1. Instalar o 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 relatar:

1. ✅ Número de rastros encontrados
2. ⚠️ Quaisquer 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: "Tempo limite de conexão Neo4j"
- 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 tempo limite do Neo4j. Recomendo verificar a conexão do banco de dados.

---

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

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

Executar:

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

Analisar JSON e relatar:

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 Detalhada - Rastro abc123

Objetivo: Usuário perguntou "Encontrar 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: "Nó não encontrado"
   → 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 erros na ferramenta get_node_details
2. Filtrar nós excluídos nos resultados da busca
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 da sessão com carimbo de data/hora
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

Relatar:

✅ Sessão exportada com sucesso!

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

Você pode agora:
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 relatar:

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. Tempo Limite de Conexão Neo4j (4 ocorrências)
   - Agente: cypher
   - Ferramenta: search_nodes
   - Primeira ocorrência: 14:32
   - Última ocorrência: 14:45
   - Padrão: Ocorre durante pico de carga

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

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

💡 Recomendações:
1. Adicionar lógica de repetição para tempos limite do Neo4j
2. Implementar limitação de taxa para o 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:

   • O rastreamento pode estar desabilitado
   • Verificar: LANGCHAIN_TRACING_V2=true no ambiente
   • Verificar: LANGCHAIN_API_KEY está configurada
   • Verificar se o agente realmente foi executado

3. Se rastros encontrados:

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

---

Caso de Uso 2: "Ferramenta Errada Chamada"

Usuário diz: "Por que 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 a 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. Pesquisar 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?
   • A recuperaçã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 chamada de ferramenta
   • 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

Use para: Inspeção visual rápida, exibir para usuários

Formato JSON

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

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

Formato Raw

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

Use para: Redirecionar para outros comandos, automação

---

Recursos Avançados

Filtragem por Tempo

# Após um carimbo de data/hora 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 Simultânea (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. Rastreamento desabilitado
3. Nome do projeto incorreto
4. Problemas com a chave da API

Soluções:

# 1. Tentar um 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 o rastreamento está habilitado no seu código
# Verificar: LANGCHAIN_TRACING_V2=true

"Projeto não encontrado"

Solução:

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

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

# 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 Regulares de Saúde

# 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. Documente Descobertas

Quando encontrar bugs:

1. Exporte o rastro problemático
2. Salve na pasta error-cases/
3. Anote o que deu errado em um README
4. Compartilhe 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 <id-do-erro> --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 <id-do-rastro> --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

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

---

Notas para o Claude

• Sempre verificar se langsmith-fetch está instalado antes de executar comandos
• Verificar 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
• Ao exportar sessões, crie estruturas de pastas organizadas
• Sempre forneça análises claras e insights acionáveis
• Se os 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