Integração Kelet
Entre no modo de planejamento imediatamente. Primeira ação do skill: chamar EnterPlanMode para que toda a sequência de análise → mapeamento → sinais → plano seja executada em modo somente leitura. Só chame ExitPlanMode após o usuário aprovar o plano de implementação final na Aprovação de Implementação.
Estrela-guia: a melhor experiência do desenvolvedor, o menor tempo possível para gerar valor. O desenvolvedor deve sentir que o Kelet se integrou sozinho — mínimo de entradas, máximo de valor visível imediatamente no console.
Kelet nunca gera exceções. Todos os erros do SDK são silenciados — uma integração mal configurada parece idêntica a uma funcional.
Busque documentação atualizada antes de escrever código: GET https://docs-ai.kelet.ai/chat?q=<pergunta> (preferencial) ou busque https://kelet.ai/docs/llms.txt para o índice.
Onboarding
Abra com um banner de boas-vindas: 🕵️ Bem-vindo ao Kelet — seu detetive de IA. Kelet é um agente de raciocínio que ingere traces + sinais, agrupa falhas e sugere correções. Ensine esses conceitos antes de qualquer código — mantenha a metáfora do detetive viva ao longo dos tópicos:
- Trace = a cena do crime. Cada chamada de LLM + uso de ferramenta é gravado automaticamente após
kelet.configure(). - Sinal = a dica. 👎, editar, abandonar — aponta o detetive para algo que vale a pena investigar. Não é um veredito: 👎 significa comece a procurar aqui.
- Sintético = ferramentas forenses. Sinais automatizados a partir de dados de trace. Sem código.
- Sessão = o arquivo do caso. Traces agrupados por uma unidade de trabalho.
- Projeto = a jurisdição. Um por caso de uso agêntico. Projeto errado = invisível na RCA.
- Em seguida: análise silenciosa + ≤3 chamadas
AskUserQuestion(idealmente 2)
Modos de Integração
Leve (padrão): O menor número possível de alterações de código — idealmente apenas kelet.configure(). Adicione agentic_session() apenas se necessário (consulte Sessões), sintéticos gerenciados (zero código) e no máximo 1–2 sinais codificados apenas se eles estiverem trivialmente conectados a um hook existente. Padrão para isso, a menos que o desenvolvedor diga "expandir", "adicionar mais sinais" ou "ir a fundo".
Completa: todas as camadas de sinal + interface VoteFeedback + mapeamento completo de modos de falha.
Na dúvida: leve. Cada alteração extra de código é um custo para o desenvolvedor.
Estilo de Apresentação
Tom: caloroso + especialista. Conceito antes da mecânica. Abra cada checkpoint com um banner: <emoji> <FASE> — uma palavra, MAIÚSCULA, nada mais. Fases: MAPEAMENTO, SINAIS, PLANO, IMPLEMENTAR, VERIFICAR.
Rastreador de progresso — exatamente esses rótulos:
📍 Mapeamento 🔄 → Sinais ○ → Plano ○ → Implementar ○ → Verificar ○
Trabalho interno (ex.: 0a, 0b, 1, sub-passos) permanece silencioso. O usuário vê o progresso apenas quando uma fase muda para ✅.
Regras Principais
- Seja conciso — nunca se repita. Cada token custa tempo. Diga cada fato uma vez, colete dados metodicamente, não reexplique o que já foi abordado.
- Sempre use
AskUserQuestionpara entrada — nunca texto livre. UsemultiSelect: truepara listas. - No máximo 3 chamadas
AskUserQuestionno total (idealmente 2). Se você puder inferir — não pergunte. - Pré-voo (fora do orçamento): Se não houver descrição do aplicativo na mensagem de gatilho, pergunte: "O que seu aplicativo de IA faz e como os usuários interagem com ele?" antes de ler arquivos.
- Análise silenciosa primeiro. Permaneça no modo de planejamento pelos Checkpoints 1 e 2; só chame
ExitPlanModena Aprovação de Implementação. - Se Kelet já estiver nas dependências: pule a configuração, concentre-se no que foi perguntado. Análise + Verificar ainda se aplicam.
- Combine com o estilo visual do aplicativo. Qualquer UI adicionada (botões VoteFeedback, botão de copiar, repetir, etc.) deve usar as classes CSS existentes do aplicativo, tokens de design e padrões de componente — não estilos inline arbitrários ou emojis padrão. Leia a folha de estilo e os componentes existentes antes de escrever children.
Slots de perguntas:
- Checkpoint 1 — confirmar mapa do projeto/fluxo de trabalho
- Checkpoint 2 — confirmar plano + coletar chaves + nome do projeto
- Apenas se a implantação for verdadeiramente desconhecida e os segredos não puderem prosseguir com segurança
Nenhuma microconfirmação entre esses.
Passo de Análise (Silencioso)
🧠 Leia tudo antes de perguntar qualquer coisa. O desenvolvedor deve ser confirmado, não questionado.
Leia silenciosamente — nenhuma pergunta ainda. Cubra:
- Dependências — frameworks de IA, pilha de UI, gerenciador de pacotes
- Ponto de entrada — onde
configure()deve ir - Locais de chamada LLM — fluxos, padrões de orquestração
- Rastreamento de sessão — IDs de conversa, IDs de requisição, chaves Redis, colunas de BD. Avalie a semântica: o ID candidato muda ao resetar/nova conversa? Se não, levante a incompatibilidade. Consulte references/implementation.md.
- UI de feedback existente — polegares, avaliações, edições, repetições, botões de copiar. Conecte-se a eles; não substitua.
- Infra de implantação — escaneie antes de perguntar:
helm/,charts/,.github/workflows/,vercel.json,railway.json,render.yaml,fly.toml,docker-compose.yml,Procfile,*.tf,template.yaml
Pule estilo, autenticação, lógica de negócios irrelevante. Sinalize outros repositórios/serviços no fluxo agêntico — o desenvolvedor deve executar este skill lá também.
Construa o Mapa do Projeto:
Caso de uso: [o que os agentes fazem]
Fluxos → Projetos Kelet:
- fluxo "X" → projeto "X"
Virado para o usuário: sim/não
Pilha: [servidor] + [framework LLM]
Config: .env / .envrc / k8s
Implantação: [plataforma | nenhuma encontrada]
Modo: leve | completo
Construa um diagrama de arquitetura ASCII mostrando o fluxo de dados e onde os IDs de sessão trafegam.
Checkpoint 1: Confirmação de Mapeamento
Apresente o diagrama + mapa do projeto + modo de integração + breve resumo do fluxo de trabalho (etapas, como são o sucesso/fracasso da perspectiva do agente).
AskUserQuestion: "Este diagrama, mapa e resumo do fluxo de trabalho representam com precisão seu sistema? Algo que eu perdi?"
Se a semântica da sessão for genuinamente ambígua — inclua-a nesta pergunta, não use um slot separado.
Se as correções alterarem a contagem de fluxos, framework ou estrutura da sessão — refaça o passo de análise. Não prossiga para a análise de sinais até que seja confirmado.
Passo de Análise de Sinais (Raciocínio Interno)
🧠 NÃO MOSTRE ESTE RACIOCÍNIO AO USUÁRIO. Apresente as propostas finais no Checkpoint 2.
Pense como um investigador plantando pistas: se algo der errado depois, quais migalhas de pão ajudariam a rastrear a origem? Não preveja falhas — instrumente os momentos que as revelariam depois do fato.
O único filtro: Kelet pode derivar esta pista do trace da sessão? → sintético (zero código). Requer uma ação humana ou evento externo? → sinal codificado.
Sintético (plataforma, nenhum código do cliente):
Escolha avaliadores que capturem sinais de qualidade significativos para este caso de uso específico. Âncora: Conclusão de Tarefa. Adicione 1–2 que reflitam a aparência de "bom" e "ruim" para este aplicativo. UM avaliador por dimensão — duplicar uma dimensão multiplica o ruído. Consulte references/signals.md para a lista predefinida.
Codificado — frontend (leve: 0–2 máx):
Quase sempre frontend — humano reagindo à saída de IA. Lado do servidor apenas se o consumidor for outro sistema ou se o feedback chegar por um endpoint (ex.: /approve).
- Voto →
VoteFeedback, edições →useFeedbackState, eventos comportamentais →useKeletSignal kind:FEEDBACK·EDIT·EVENT·METRIC·ARBITRARY—source:HUMAN·LABEL·SYNTHETIC- Varredura de UI React: Inputs de edição na saída de IA →
useFeedbackState; copiar para área de transferência, repetir, resetar sessão →useKeletSignal. Copiar sempre vale a pena propor para aplicativos que renderizam texto de IA — mesmo que nenhum botão exista ainda, é uma ação natural e um sinal implícito forte. Proponha 1–2 máx.
Codificado — lado do servidor: apenas se não houver UI do navegador ou feedback for orientado por endpoint.
Prepare-se para o Checkpoint 2: propostas de sinal + sugestão de nome de projeto + prévia do "o que você verá".
Checkpoint 2: Confirmar Plano + Coletar Entradas
Apresente as descobertas de sinal + plano leve completo. Não peça ao desenvolvedor para projetá-lo — proponha-o.
Ainda no modo de planejamento — não chame ExitPlanMode ainda.
Único AskUserQuestion (multiSelect: true), estruturado como:
- Avaliadores sintéticos propostos (multiSelect) — liste cada avaliador proposto como uma opção para que o desenvolvedor escolha explicitamente quais entram no projeto. Inclua "Nenhum" como uma opção.
- Aprovação do plano — "O resto do plano parece correto?"
- Chaves + nome do projeto (apenas o que estiver faltando):
KELET_API_KEY(sk-kelet-...) — obtenha em console.kelet.ai/api-keys. Necessário para criação automática de sintéticos.- Chave publicável (
pk-kelet-...) — apenas se VoteFeedback estiver no plano. - Nome do projeto: crie-o primeiro em console.kelet.ai → nav superior → Novo Projeto. Nome errado = falha de roteamento silenciosa; servidor retorna 404 com uma dica, levante-a.
- Modo de chave de API (apenas se avaliadores sintéticos foram selecionados):
- "Cole a chave secreta (sk-kelet-...)" → criação automática primária.
- "Vou pegar uma" → pare: "Obtenha uma chave em console.kelet.ai/api-keys (10 segundos), cole-a aqui para continuar."
- "Não posso colar segredos aqui" → fallback de deep link.
Criando os avaliadores
Primário (chave colada): antes do curl, imprima literalmente:
⏳ Criando seus avaliadores. Isso leva 1–3 minutos (às vezes até 5) — Kelet gera cada configuração com um LLM e executa um passo de deduplicação. Aguente firme; não cancele.
Em seguida, execute conforme references/signals.md § Primário: Chamada de API.
Em 200: ✅ Kelet agora está observando {projeto}. Primeiros resultados do avaliador em ~3min em https://console.kelet.ai/{projeto}/sinais
Fallback (não pode colar): construa o link markdown base64 conforme references/signals.md.
O que você verá
Mostre a tabela — apenas linhas para itens no plano proposto:
| Após implementar | Visível no console Kelet |
|---|---|
kelet.configure() | Spans LLM em Traces: modelo, tokens, latência, erros |
agentic_session() | Visualização de Sessões: conversa completa agrupada para RCA |
| VoteFeedback | Sinais: 👍/👎 correlacionados ao trace exato |
Sinais de edição (useFeedbackState) | Sinais: o que os usuários corrigiram — revela erros do modelo |
| Sintéticos da plataforma | Sinais: pontuações de qualidade automatizadas |
Escreva código source=SYNTHETIC apenas se o desenvolvedor pedir explicitamente E a plataforma não conseguir implementá-lo — explique por que a plataforma não pode lidar com isso e peça confirmação antes de prosseguir.
Aprovação de Implementação
Exceção: se a implantação foi sinalizada como desconhecida E os segredos não podem ser tratados com segurança, use o slot de pergunta 3: "Como você faz a implantação? Como os segredos são gerenciados?" → siga references/deployment.md. Pule se a implantação foi identificada ou for irrelevante.
Apresente o plano de implementação completo, chame ExitPlanMode para aprovação e implemente.
Chaves de API
Dois tipos — nunca misture:
- Secreta (
KELET_API_KEY,sk-kelet-...): apenas no servidor. O SDK aceita qualquer tipo de chave sem gerar erro — usar a errada é uma falha silenciosa. - Publicável (
VITE_KELET_PUBLISHABLE_KEY/NEXT_PUBLIC_KELET_PUBLISHABLE_KEY,pk-kelet-...): apenas no frontend.
Escreva no config: .env → CHAVE=valor · .envrc → export CHAVE=valor · K8s → manifesto de segredos. Adicione ao .gitignore. Nunca codifique o nome do projeto — sempre variável de ambiente. Quando o aplicativo tiver tanto um servidor quanto um frontend, escreva as chaves em ambos os arquivos env — chave secreta no .env do servidor, chave publicável em frontend/.env (ou onde Vite/Next a pegar). Siga references/deployment.md para produção.
Sessões
Uma sessão = uma unidade de trabalho. Novo contexto = nova sessão.
agentic_session() NÃO é necessária (instrumentação automática):
LangChain/LangGraph · LlamaIndex · CrewAI · Haystack · Google ADK (kelet[google-adk] recomendado) · pydantic-ai · DSPy · Langfuse · Langroid · qualquer coisa usando OpenInference/OpenLLMetry
⚠️ Substituição — leia o bloco OBRIGATÓRIO abaixo primeiro. A lista acima assume que o framework também é dono do ID da sessão (execuções curtas em processo). Se o aplicativo gerar o ID da sessão por conta própria (Redis, BD, UUID emitido pelo servidor) ou você orquestrar várias chamadas LLM entre requisições, agentic_session(session_id=...) é OBRIGATÓRIA independentemente do framework — o framework não sabe seu ID e os spans ficam desvinculados. Na dúvida, envolva.
⚠️ LiteLLM puro — traces são capturados automaticamente, mas o LiteLLM não propaga o contexto de sessão/agente em seus spans. Se o LiteLLM for chamado diretamente (não por meio de outro framework compatível, como Google ADK), envolva as chamadas em agentic_session() (e opcionalmente kelet.agent()) para agrupá-las. Quando o LiteLLM roda sob outro framework instrumentado, o span pai fornece contexto — nenhum envoltório necessário.
Se não listado — pesquise antes de omitir.
agentic_session(session_id=...) OBRIGATÓRIA (ambas silenciosas se omitidas):
- Aplicativo é o dono do ID da sessão (Redis, BD, gerado pelo servidor): framework não o conhece → o vínculo do VoteFeedback quebra
- Você é o dono do loop (agente A → agente B, Temporal, orquestradores personalizados): nenhum framework define o ID de sessão geral → spans aparecem como traces desvinculados. TS:
agenticSession({ sessionId }, callback).
⚠️ Vercel AI SDK — framework compatível mas não define IDs de sessão: use agenticSession() no nível da rota.
Identidade do usuário ≠ ID da sessão. Identificadores estáveis (telefone, email, user_id) sobrevivem a sessões. Se o aplicativo tiver uma identidade de usuário estável: gere UUID por conversa como kelet_session_id, regenere no reset. Avalie silenciosamente o identificador: não-PII (ID de usuário interno, UUID opaco) → conecte como user_id= sem perguntar. PII óbvio (telefone, email) → omita, mas destaque-o proeminentemente: "⚠️ user_id= não foi definido — seu identificador de usuário é PII (telefone/email). Se você tiver um ID de usuário não-PII, passe-o aqui para habilitar RCA por usuário." Genuinamente ambíguo → inclua no Checkpoint 1, não use um slot separado.
Consulte references/api.md para assinaturas. Consulte references/stack-notes.md para pegadinhas por pilha.
Referência de Implementação
Consulte [references/implementation.md](references/
…
[truncado para tradução]