Workshop Langfuse — o ciclo de engenharia de IA, de ponta a ponta
Um workshop passo a passo de Langfuse baseado em uma pequena aplicação TypeScript: o Dad IT Support Agent. Ele percorre todo o ciclo de engenharia de IA com Langfuse...
O material do workshop é mantido no repositório público langfuse/langfuse-workshop. Use o repositório para executar a aplicação, acessar os branches de checkpoint e fazer a configuração local.
Este é um workshop passo a passo de Langfuse baseado em uma pequena aplicação TypeScript: o Dad IT Support Agent. Ele percorre todo o ciclo de engenharia de IA com Langfuse: tracing, gerenciamento de prompts, monitoramento, datasets, experimentos e avaliação.
Você pode concluir o workshop por conta própria usando as lições para participantes ou usar as notas para instrutores para ensinar o mesmo conteúdo a um grupo.
Para participantes
Comece pelas lições em docs/learner/. Cada lição indica qual checkpoint usar, o que alterar no código ou configurar no Langfuse e como verificar o resultado.
Use esse percurso se quiser:
- Registrar seu primeiro trace a partir de uma aplicação LLM real e entender o resultado.
- Mover um prompt para o Langfuse, versionando as mudanças e vinculando-as aos traces.
- Monitorar o comportamento em produção sem ler cada trace manualmente.
- Criar um dataset, executar experimentos e avaliar mudanças com evidências.
- Examinar uma implementação de referência completa em TypeScript e reaproveitar seus padrões.
Não é necessário ter instrutor. As lições são completas o bastante para realizar o workshop de forma autoguiada.
Para instrutores
O guia para instrutores é voltado a quem deseja ensinar Langfuse. Use as notas em docs/instructor/ junto às lições ao conduzir um workshop ao vivo, gravar uma apresentação ou adaptar o material para uma equipe.
Para a preparação, incluímos um guia e slides em docs/preparation_and_materials/.
O workshop não depende de um instrutor. As notas acrescentam pontos de ensino, ritmo de demonstração, lembretes de preparação e armadilhas comuns; não são necessárias para quem realiza o workshop sozinho.
Escopo do workshop
A aplicação de exemplo é um pequeno chat web no qual o pai pede ajuda com o iPhone. O agente se chama Specs e responde com instruções passo a passo. Por baixo dos panos, é um loop normal de chamadas de ferramentas da OpenAI com duas ferramentas locais.
main contém a aplicação de referência completa e a documentação atual do workshop. Use-o para examinar a implementação concluída ou comparar seu trabalho com o estado final. Os exercícios começam em tags de checkpoint.
Módulos
| Etapa | Lição do participante | Notas do instrutor | Checkpoint | O que você aprenderá |
|---|---|---|---|---|
| 00 | Configuração | Notas do instrutor | checkpoint/00-setup | Chaves, instalação e execução da aplicação. |
| 01 | Aplicação base | Notas do instrutor | checkpoint/01-base-app | Conhecer a aplicação. Nada para construir. |
| 02 | Tracing | Notas do instrutor | checkpoint/02-tracing | Registrar cada etapa do agente: generations, raiz e spans das ferramentas. |
| 03 | Gerenciamento de prompts | Notas do instrutor | checkpoint/03-prompt-management | Mover o prompt de sistema para o Langfuse. |
| 04 | Monitoramento | Notas do instrutor | checkpoint/04-monitoring | Detectar solicitações fora do escopo e discordância do usuário. |
| 05 | Dataset | Notas do instrutor | checkpoint/05-dataset | Transformar o escopo do produto em exemplos reutilizáveis. |
| 06 | Experimentos | Notas do instrutor | checkpoint/06-experiments | Executar o agente no dataset e pontuar cada item. |
| 07 | Avaliação | Notas do instrutor | checkpoint/07-evaluation | Mudar uma coisa, executar novamente e comparar. |
| 08 | Encerramento | Notas do instrutor | checkpoint/08-wrap-up | Aplicar o ciclo à sua própria aplicação. |
Como percorrer o workshop
main é a implementação de referência completa. Para a parte prática, faça checkout do checkpoint indicado na lição, implemente as mudanças que faltam e verifique o resultado antes de avançar.
checkpoint/00-setup e checkpoint/01-base-app contêm intencionalmente a mesma aplicação base sem tracing. Setup usa esse estado para validar chaves, dependências e portas; Base App o usa para orientação. O tracing começa em 02-tracing.
O servidor e os scripts auxiliares do npm tratam o .env do repositório como fonte da verdade do Node. Variáveis exportadas no shell por outros projetos não sobrescrevem .env; altere nesse arquivo as chaves, o host do Langfuse, os labels de prompts e os nomes dos datasets.
O workshop é curto o bastante para ser concluído em uma sessão, e cada módulo pode ser usado separadamente se você quiser apenas uma parte do ciclo.
Estrutura do repositório
docs/learner/contém as lições autoguiadas.docs/instructor/contém as notas para quem ensina as mesmas lições.docs/images/contém capturas e diagramas agrupados por lição.src/contém a aplicação de exemplo.scripts/contém scripts auxiliares de datasets e prompts usados nas lições seguintes.
Próximos passos
- Percorra os módulos em ordem, começando por
docs/learner/00-setup.md. - Vá diretamente ao capítulo que corresponde ao que você quer aprender.
- Instale a skill do Langfuse (
/langfuse) para aplicar esses padrões à sua base de código. - Para uma visão mais ampla de cada capítulo, consulte a Langfuse Academy.