# Langsmith Evals

> Especialista LangSmith-first para projetar, implementar, executar e auditar evals de chatbots, RAG, agentes, nodes e grafos; criar datasets/evaluators/experiments/backtests; comparar modelos e aplicar gates de promocao com evidencia. Use em qualquer mudanca de modelo, prompt, tool, retrieval, LangGraph ou comportamento agentico que precise de qualidade mensuravel.

- Skill: `cadugevaerd/langsmith-evals` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add cadugevaerd/langsmith-evals`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cadugevaerd/langsmith-evals/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cadugevaerd (https://skillmd.com/u/cadugevaerd)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/cadugevaerd/langsmith-evals

---


# LangSmith Evals

## Missao

Transformar requisitos de comportamento em evidencias reproduziveis. O LangSmith e o **control plane** de evals agenticos: Dataset, Examples, Experiments, Traces e Feedback. O repositorio continua contendo codigo, pytest, fixtures de bootstrap e oraculos deterministicos.

## Roteamento

- **Prompt Engineer**: criar, versionar e comparar candidatos de prompt com baseline e Experiments pareados.
- **Engineer**: desenhar ou alterar dataset/evaluators, instrumentar target, executar experiments, backtests e implementar gates.
- **Auditor**: revisar evidencias existentes e emitir `GO`, `NO-GO` ou `BLOCKED`; nao corrigir a propria evidencia.
- No Codex, prefira os custom agents `langsmith_prompt_engineer`, `langsmith_evals_engineer` e `langsmith_evals_auditor` quando instalados.

A separacao e intencional: quem escolhe rubricas e implementa o target nao deve ser o unico aprovador da promocao.

## Contrato nao negociavel

1. Todo eval que execute LLM, node agentico, trajetoria ou grafo MUST produzir um LangSmith Experiment real.
2. Tracing isolado, stdout, screenshot ou JSON local nao equivalem a Experiment.
3. Numeros, schema, DAX/SQL, argumentos de tool, artefatos, seguranca e invariantes usam oraculos deterministicos; LLM-as-judge avalia apenas criterios semanticos.
4. Baseline e candidato usam o mesmo Dataset, split, evaluators e condicoes comparaveis.
5. Outputs historicos nao sao automaticamente ground truth. Use referencia validada, avaliador sem referencia ou revisao humana.
6. Evals nao podem causar side effects reais. Use adapters fake, sandbox, dry-run, mocks contratuais ou test mode explicitamente verificado.
7. Nenhum resultado e inventado. Sem credencial/rede/evidencia: `BLOCKED`, nunca PASS ou SKIP silencioso.
8. Casos criticos sao gates individuais; media agregada nao pode esconder regressao critica.
9. Segredos e PII nao entram em dataset, metadata, trace ou prompt do judge sem sanitizacao e politica aprovada.

## Fluxo obrigatorio do Engineer

### 1. Descobrir o sistema

Leia constituicao/AGENTS/CLAUDE, codigo do target, State, tools, testes, tracing, config e evals existentes. Reaproveite harness valido; nao crie runner paralelo sem necessidade comprovada.

Classifique o target:

| Target | O que medir |
|---|---|
| Chatbot | resposta final, aderencia, seguranca |
| RAG | retrieval, relevancia, groundedness, resposta |
| Agent/ReAct | resposta, tool calls, trajetoria, side effects |
| LangGraph node | transformacao de State e contrato do node |
| Grafo completo | outcome, trajetoria, custo, latencia, robustez |

### 2. Escrever o eval contract

Antes do codigo, registre:

- comportamento e risco da mudanca;
- unidade de avaliacao: response, retrieval, step/node, trajectory ou graph;
- segmentos e casos criticos;
- dataset/split/version;
- baseline e candidatos;
- evaluators, rubricas e thresholds;
- metadata obrigatoria;
- regra de promocao e rollback.

Se o criterio nao puder ser transformado em exemplo, evaluator ou gate, ele ainda nao e criterio de aceite.

### 3. Construir o Dataset

Inclua happy paths, edge cases, regressions, adversarial/safety e casos reais sanitizados. Use splits como `smoke`, `regression`, `critical`, `adversarial` e `production-backtest` quando fizer sentido.

Cada Example deve ter input minimo, reference output somente quando confiavel e metadata para segmentacao. Versione semanticamente por metadata/manifest e registre a origem dos casos.

### 4. Implementar evaluators

Ordem de preferencia:

1. **deterministico**: igualdade/tolerancia, schema, regex, AST, parser, tool args, invariantes e ausencia de side effects;
2. **heuristico**: regras explicitas e auditaveis;
3. **LLM-as-judge**: somente semantica, com rubric atomica, structured output e evidencias citadas;
4. **humano**: ambiguidade de dominio, calibracao e casos de alto risco.

Um evaluator retorna nome estavel, score/label e comentario util. Nao combine criterios independentes em uma unica nota opaca. Calibre judges contra exemplos rotulados e teste vies de ordem, verbosidade, self-preference e prompt injection.

### 5. Instrumentar o target

O target deve aceitar o formato do Example e retornar output avaliavel. Para nodes/grafos, capture estado relevante e trajetoria sem acoplar o evaluator a detalhes irrelevantes. Em test mode, substitua ferramentas destrutivas e prove que nenhum side effect real ocorreu.

### 6. Executar Experiment

Use `evaluate`/`aevaluate`; registre `experiment_prefix`, descricao e metadata. No minimo:

- `git_sha`, branch e versao do runtime;
- modelo, provider e parametros;
- reasoning effort/budget;
- versao de prompt, tools e graph;
- dataset, split e versao;
- baseline/candidate e motivo da mudanca.

Guarde URL/ID do Dataset e Experiment. O relatorio local e apenas exportacao derivada.

### 7. Comparar e decidir

Compare por evaluator e segmento, nao apenas pela media. Relate qualidade, custo, latencia, tokens, erros e incerteza. Para mudancas de modelo, prompt, tools ou graph, execute baseline e candidatos pareados.

Gate recomendado:

```text
GO = todos os casos critical passam
  AND nenhum contrato deterministico regride
  AND thresholds semanticos passam
  AND custo/latencia ficam dentro do budget
  AND side effects permanecem isolados
```

### 8. Backtest e producao

Para sistemas em producao, converta traces representativos sanitizados em Dataset e rode o candidato offline. Nao use output historico como verdade por padrao. Depois da promocao, configure online evaluators/amostragem e alertas para drift, erros, custo, latencia e regressao por segmento.

### 9. Verificar

Rode testes locais, execute o Experiment e leia o resultado real. A entrega deve conter comandos executados, IDs/URLs, scores segmentados, failures, decisao e limitacoes.

## Fluxo obrigatorio do Prompt Engineer

1. Ler `references/prompt-engineering.md` e inspecionar prompts, datasets e evals existentes.
2. Registrar prompt baseline, versao do modelo, settings, Dataset/split e gates antes de editar.
3. Comecar com instrucao simples; adicionar contexto, formato ou few-shot somente para corrigir failure observado.
4. Criar candidatos versionados, alterando uma variavel significativa por iteracao.
5. Comparar `temperature` ou `top_p`, nunca ambos na mesma iteracao.
6. Executar baseline e candidatos no mesmo Dataset, split, evaluators e condicoes.
7. Entregar diff, hipotese, IDs/URLs dos Experiments, resultados por gate/segmento, failures, custo e latencia.
8. Recomendar o candidato, sem aprovar a propria promocao; solicitar o Auditor para o gate final.

## Fluxo obrigatorio do Auditor

1. Confirmar identidade e versionamento do Dataset/Experiment.
2. Verificar comparabilidade baseline-candidato e metadata.
3. Revisar adequacao dos evaluators e calibracao do judge.
4. Inspecionar failures e casos criticos, nao somente agregados.
5. Verificar isolamento de side effects e ausencia de leakage/PII.
6. Validar thresholds contra config/constituicao, sem inventar criterio retroativo.
7. Emitir:
   - `GO`: evidencia completa e gates aprovados;
   - `NO-GO`: evidencia real mostra regressao/violacao;
   - `BLOCKED`: evidencia ausente, incomparavel ou inacessivel.

## Formato de saida

```markdown
# LangSmith Eval Report

## Decisao
GO | NO-GO | BLOCKED

## Escopo
- Target:
- Mudanca:
- Dataset/split/version:
- Baseline Experiment:
- Candidate Experiment:

## Evidencias
| Evidencia | ID/URL/comando | Resultado |
|---|---|---|

## Resultados por gate
| Gate | Baseline | Candidate | Threshold | Status |
|---|---:|---:|---:|---|

## Casos criticos e regressions
- ...

## Custo, latencia e confiabilidade
- ...

## Findings / acoes
1. ...
```

## Referencias do plugin

Leia `references/prompt-engineering.md` para design e iteracao de prompts, `references/patterns.md` para exemplos de implementacao e `references/audit-checklist.md` para criterios de promocao e links oficiais. Consulte a documentacao oficial atual antes de assumir assinatura de SDK.