00 Configuração

Deixe a aplicação do workshop rodando localmente com as credenciais da OpenAI e do Langfuse. Depois, você pode percorrer 01-base-app e começar a implementar em 02-tracing.

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.

Ver este arquivo Markdown

Objetivo

Deixe a aplicação do workshop rodando localmente com as credenciais da OpenAI e do Langfuse. Depois, você pode percorrer 01-base-app e começar a implementar em 02-tracing.

Pré-requisitos

Node.js ^20.19.0 || >=22.12.0 — verifique com node -v e atualize antes da instalação se a versão for inferior (nvm install 22 ou o equivalente para asdf, fnm ou volta).

Uma versão mais antiga falha de modo fácil de interpretar errado. O binário específico de plataforma do Vite é uma dependência opcional; por isso, o npm a ignora sem informar erro: npm install parece funcionar, e o problema só surge depois, quando npm run dev não consegue iniciar o Vite. Se você atualizar o Node após instalar, execute npm ci novamente para baixar o binário ignorado.

Ponto de partida

Clone o repositório do workshop, entre no diretório e faça checkout do checkpoint de configuração deste capítulo:

git clone https://github.com/langfuse/langfuse-workshop.git
cd langfuse-workshop
git checkout checkpoint/00-setup

Esse checkpoint contém intencionalmente a mesma aplicação base sem tracing de checkpoint/01-base-app. Use-o para confirmar suas chaves de API, dependências e portas locais antes de avançar para os capítulos de implementação. As chaves do Langfuse são configuradas agora, mas os traces só começam depois da instrumentação em 02-tracing.

Etapa 1 — Obter as chaves de API

OpenAI — acesse platform.openai.com → API Keys → crie uma chave. Copie o valor sk-....
Langfuse — cadastre-se em langfuse.com na região EU, crie um projeto e copie as chaves pública e secreta em Settings → API Keys.

Etapa 2 — Instalar a skill e a CLI do Langfuse

Os módulos seguintes controlam o Langfuse por meio de um agente de programação, que precisa da skill langfuse e da CLI do Langfuse.

Cole a instrução abaixo no seu agente para instalar ambos:

"Instale a skill langfuse de https://github.com/langfuse/skills/tree/main/skills/langfuse e instale a CLI do Langfuse com npm install -g langfuse-cli."

Se preferir instalar manualmente:

# Langfuse CLI
npm install -g langfuse-cli

# Langfuse Skill:
npx skills add langfuse/skills --skill "langfuse"

Etapa 3 — Configurar `.env`

cp .env.example .env

Preencha:

OPENAI_API_KEY=sk-...
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

Mantenha os demais valores padrão.

A aplicação sempre carrega o arquivo .env deste repositório para o servidor e os scripts auxiliares. Valores LANGFUSE_*, OPENAI_* ou DATASET_NAME exportados no seu shell por outro projeto não sobrescrevem esse arquivo. Para mudar a configuração do workshop, edite .env.

Mantenha esses valores apenas no .env local. Não cole chaves reais de API em anotações, transcrições, capturas de tela ou chats compartilhados.

Etapa 4 — Instalar e executar

npm install
npm run dev

Abra http://127.0.0.1:3333.

Para verificar o servidor separadamente, acesse http://127.0.0.1:8787/api/health ou http://127.0.0.1:8787/api/support-context. Durante npm run dev, 127.0.0.1:8787/ não é a URL principal da aplicação.

Se nada carregar em 127.0.0.1:3333, volte a saída de npm run dev até as linhas [dev:client]. concurrently mantém a API rodando mesmo quando o Vite encerra, então o terminal parece ativo — e abrir 127.0.0.1:8787/ nesse estado responde ENOENT ... dist/index.html, o que só indica a ausência do build de produção e nada diz sobre a falha real. Um erro Cannot find native binding nessas linhas [dev:client] aponta para a versão do Node; consulte os Pré-requisitos.

Etapa 5 — Confirmar o que aparece

Você deve ver o chat Dad IT Support Agent:

o mascote Specs no topo
uma saudação de Specs
sugestões abaixo da saudação
o painel do iPhone à direita ("Dad" + detalhes do iPhone 15)

Como Specs atende a uma solicitação — um agente, duas ferramentas, um modelo, cada etapa como uma observação no trace.

Como verificar a conclusão

npm run dev está rodando e escutando em http://127.0.0.1:3333 (cliente) e http://127.0.0.1:8787 (servidor da API).
http://127.0.0.1:8787/api/health ou http://127.0.0.1:8787/api/support-context retorna uma resposta real.
O navegador mostra a saudação de Specs, não um erro.
Enviar uma das sugestões retorna uma resposta real do modelo sobre o iPhone.

Estado final

Seu ambiente está pronto. Para construir o workshop passo a passo, percorra 01-base-app se quiser conhecer a aplicação e depois faça checkout de checkpoint/02-tracing para as primeiras mudanças no código.