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

Ativa automaticamente quando o usuário menciona:

• 🐛 "Depure meu agente" ou "O que deu errado?"
• 🔍 "Mostre os 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 o uso de tokens"
• 🔧 "Quais ferramentas foram chamadas?" ou "Mostre o fluxo de execução"

Pré-requisitos

1. Instale langsmith-fetch

pip install langsmith-fetch

2. Configure Variáveis de Ambiente

export LANGSMITH_API_KEY="your_langsmith_api_key"
export LANGSMITH_PROJECT="your_project_name"

Verifique a 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 pergunta: "O que aconteceu agora?" ou "Depure meu agente"

Execute:

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

Analise e relate:

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:

Found 3 traces in the last 5 minutes:

Trace 1: ✅ Success
- Agent: memento
- Tools: recall_memories, create_entities
- Duration: 2.3s
- Tokens: 1,245

Trace 2: ❌ Error
- Agent: cypher
- Error: "Neo4j connection timeout"
- Duration: 15.1s
- Failed at: search_nodes tool

Trace 3: ✅ Success
- Agent: memento
- Tools: store_memory
- Duration: 1.8s
- Tokens: 892

💡 Issue found: Trace 2 failed due to Neo4j timeout. Recommend checking database connection.

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

Quando o usuário fornece: ID do rastro ou diz "investigue aquele erro"

Execute:

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

Analise o JSON e relate:

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 da causa raiz
6. 🔧 Correção sugerida

Exemplo de formato de resposta:

Deep Dive Analysis - Trace abc123

Goal: User asked "Find all projects in Neo4j"

Execution Flow:
1. ✅ search_nodes(query: "projects")
   → Found 24 nodes

2. ❌ get_node_details(node_id: "proj_123")
   → Error: "Node not found"
   → This is the failure point

3. ⏹️ Execution stopped

Root Cause:
The search_nodes tool returned node IDs that no longer exist in the database,
possibly due to recent deletions.

Suggested Fix:
1. Add error handling in get_node_details tool
2. Filter deleted nodes in search results
3. Update cache invalidation strategy

Token Usage: 1,842 tokens ($0.0276)
Execution Time: 8.7 seconds

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

Quando o usuário diz: "Salve esta sessão" ou "Exporte os rastros"

Execute:

# Create session folder with timestamp
SESSION_DIR="langsmith-debug/session-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$SESSION_DIR"

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

# Export threads (conversations)
langsmith-fetch threads "$SESSION_DIR/threads" --limit 20

Relate:

✅ Session exported successfully!

Location: langsmith-debug/session-20251224-143022/
- Traces: 42 files
- Threads: 8 files

You can now:
1. Review individual trace files
2. Share folder with team
3. Analyze with external tools
4. Archive for future reference

Session size: 2.3 MB

Fluxo de Trabalho 4: Detecção de Erros

Quando o usuário pergunta: "Mostre os erros" ou "O que está falhando?"

Execute:

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

# Search for errors
grep -i "error\|failed\|exception" recent-traces.json

Analise e relate:

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 Falhados: 7 (taxa de falha de 14%)

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 o pico de carga

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

3. Ferramenta Não Encontrada (1 ocorrência)

…