💡 Como ler este módulo
Este é o módulo final da Trilha 1. Os três primeiros tópicos cobrem canais IM (Telegram, Slack, família asiática), os dois seguintes cobrem tracing (LangSmith, Langfuse), e o lab costura os dois mundos — bot + trace em tempo real. Depois desta página, você segue para a Trilha 2 e começa o DeerFlow avançado.
✈️ Telegram — bot pessoal no celular
Telegram é o canal IM mais rápido de ligar. O DeerFlow tem suporte nativo: você cria um bot via BotFather, cola o token no .env, habilita no config.yaml e reinicia. A partir daí, qualquer mensagem privada para o bot chega no lead_agent, preservando sessão por usuário e memória por usuário. Fotos, áudios e documentos funcionam nativamente.
Criar o bot via BotFather
Abra o Telegram, fale com @BotFather, use /newbot, escolha nome e username. O BotFather devolve um token — copie, guarde, nunca commite.
Token no .env
Adicione TELEGRAM_BOT_TOKEN=.... Habilite channels.telegram.enabled: true no config.yaml apontando para ${TELEGRAM_BOT_TOKEN}.
Reiniciar e testar
make doctor para confirmar que o provider do Telegram está saudável. Depois make docker-start (ou equivalente) e mande "oi" para o bot. O DeerFlow responde.
Sessão por chat
Cada chat Telegram vira uma sessão DeerFlow distinta. Isso significa memória por usuário, histórico por usuário, e a possibilidade de plugar outras pessoas no mesmo bot com contextos isolados.
💡 Dica prática
Para demos rápidas, deixe o bot privado (no BotFather, /setjoingroups desabilitado) e só envie o link para quem deve testar. Abrir o bot em grupos públicos sem rate limit é pedido de conta queimada.
💬 Slack — onde o time trabalha
Slack é onde a maioria dos times corporativos já vive. Plugar bem o DeerFlow ali é a diferença entre "interessante" e "adotado". O DeerFlow cria um Slack App com scopes mínimos, escuta via socket mode (sem precisar expor porta pública) e cada thread vira uma sessão — permitindo múltiplas conversas paralelas sem confundir histórico.
🎯 Setup mínimo
- •Criar o App — api.slack.com/apps, From scratch, nome, workspace
- •Scopes OAuth —
chat:write,im:history,app_mentions:read,files:write - •Socket mode — habilitar (evita precisar de ngrok/endpoint público)
- •Event subscriptions —
message.im,app_mention - •Install no workspace — o admin aprova o escopo
- •Token + App-Level Token — dois tokens no
.env:SLACK_BOT_TOKENeSLACK_APP_TOKEN
💡 Sessão por thread
Quando alguém abre uma thread em qualquer canal mencionando o bot, o DeerFlow trata aquela thread como uma sessão própria. O contexto dentro da thread é isolado — o agente não mistura com outras conversas. É o padrão certo para Slack: evita a bagunça de uma única sessão por canal.
🟣 Feishu, WeChat, WeCom
A família IM asiática suportada nativamente. Faz sentido se você trabalha num time com presença na China ou no ecossistema ByteDance — Feishu (Lark fora da China) é o "Slack deles", WeCom é o "Slack corporativo da Tencent", e WeChat oficial accounts cobrem o lado consumer. Mesmo fora dessas empresas, vale entender a abstração: é um ótimo estudo de caso de plugabilidade.
🎯 Abstração comum de canal IM
Todos os canais IM suportados implementam o mesmo contrato interno: recebem mensagem → rotearam para lead_agent com metadados de usuário/sessão → devolvem resposta. Isso significa que features novas (arquivos, streaming, botões de aprovação) ganhas num canal costumam chegar nos outros.
- •Feishu/Lark — app via Open Platform,
APP_ID+APP_SECRET, event subscription via webhook - •WeCom — App empresarial, token + encoding AES, callback URL
- •WeChat — conta oficial, token, modelo de reply ativo/passivo
- •Custom agents por canal — mesma feature do Slack, diferentes personas dependendo de onde o bot mora
📊 Tracing com LangSmith
Debug sem tracing é adivinhação. LangSmith é o serviço de tracing da LangChain — o DeerFlow, como roda sobre LangGraph, exporta cada execução como uma árvore hierárquica de chamadas para lá automaticamente quando habilitado. Você enxerga planejamento, skills, sub-agents, tool calls, tokens consumidos, erros, latência, tudo com timeline.
🎯 O que fica visível no LangSmith
- •Árvore de chamadas — cada nó do grafo vira um span; cliques abrem o payload de entrada/saída
- •Tokens e custo — contabilizado por execução, filtrable por skill ou provider
- •Erros — stack traces dentro do nó que falhou, sem precisar bater log no container
- •Datasets e evals — salvar prompts reais como base de regressão para mudanças futuras
- •Anotações — time pode marcar traces como "bom", "ruim", "regressão" para depois analisar padrão
💡 Setup é trivial
LANGCHAIN_TRACING_V2=true, LANGCHAIN_API_KEY=..., LANGCHAIN_PROJECT=deerflow-meu-nome no .env. Reinicie. A partir da próxima execução, tudo flui para o painel. É a integração com melhor retorno sobre o esforço do DeerFlow inteiro.
🔭 Tracing com Langfuse
Se enviar dados para um SaaS é problema — compliance, dados regulados, política corporativa — Langfuse é a alternativa. É open-source, self-hosted em minutos (Docker Compose oficial), com conceito de trace hierárquico semelhante. O DeerFlow trata os dois como intercambiáveis: você escolhe no config.yaml, muda duas linhas, os traces passam a fluir para Langfuse em vez de LangSmith.
LangSmith
- ✓Hosted, zero operação
- ✓Setup em 3 variáveis
- ✓Datasets e evals integrados
- ✓Grátis para volume baixo
- ✗Dados saem da sua infra
Langfuse
- ✓Self-hosted, dados ficam com você
- ✓Open-source (Apache 2.0)
- ✓Dashboards customizáveis
- ✓Bom para compliance/LGPD
- ✗Você mantém o Postgres e o Clickhouse
💡 Regra simples
Uso pessoal ou equipe pequena sem compliance estrito: LangSmith, sem pensar. Empresa com dados regulados, cliente que proíbe envio para SaaS, ou você simplesmente quer controle total: Langfuse self-hosted. Nos dois casos, o DeerFlow cria os traces do mesmo jeito — o destino é uma config.
🧪 Lab: bot de Telegram + trace em tempo real
O lab final da Trilha 1 costura duas peças que parecem separadas — canal IM e observabilidade — em uma única tarefa. Você vai conversar pelo celular enquanto observa os traces pipocarem no laptop. É satisfatório e educativo ao mesmo tempo: mostra que a mesma execução é auditável independentemente de onde o prompt entrou.
🎯 O que você vai fazer
Ligar um bot do Telegram ao seu DeerFlow, habilitar LangSmith (ou Langfuse), enviar 3 prompts pelo celular, e observar o trace aparecer em tempo real no navegador do laptop.
📊 Por que esse lab
Dois motivos. Primeiro, o lado prático: é a forma mais rápida de provar que o DeerFlow deixa de ser uma app local e vira um agente de verdade que você acessa pelo bolso. Segundo, o lado didático: quando o trace flui no laptop enquanto você digita no celular, a distância entre canal e execução se dissolve. O mesmo lead_agent, a mesma pilha de skills, o mesmo sandbox — só mudou a boca de entrada.
Criar o bot
Siga o passo-a-passo do tópico 1: BotFather, /newbot, token. Salve o token no .env como TELEGRAM_BOT_TOKEN. Confirme que channels.telegram.enabled: true está no YAML.
Habilitar LangSmith
Crie uma conta em smith.langchain.com (grátis), crie um projeto deerflow-trilha1, copie a API key. Adicione LANGCHAIN_TRACING_V2=true, LANGCHAIN_API_KEY=..., LANGCHAIN_PROJECT=deerflow-trilha1 no .env.
Validar e subir
make doctor — deve mostrar Telegram e LangSmith em verde. Se algum aparecer em amarelo/vermelho, conserte antes de prosseguir. Depois make docker-start.
Abrir o painel do LangSmith
No navegador do laptop, deixe o projeto deerflow-trilha1 aberto. A view "Runs" fica atualizando ao vivo. Deixe essa aba visível.
Três prompts pelo celular
Abra o bot no Telegram. Envie: (1) "oi" (fact trivial), (2) "me resuma em 3 pontos as diferenças entre RAG e fine-tuning", (3) "use deep-research para comparar 3 frameworks de agentes em 2026". Observe os três traces aparecendo no LangSmith com complexidade crescente.
Explorar um trace
Clique no trace do prompt 3 (deep-research). Abra a árvore de spans. Veja a chamada ao planner, a skill acionada, as chamadas a Tavily/InfoQuest, as chamadas ao LLM, o custo total. Esse trace é a prova visual de tudo que você aprendeu na Trilha 1.
📝 Resumo do Módulo
Próxima Trilha:
Trilha 2 — 🧭 DeerFlow Avançado I
Sub-agents, context engineering, composição de skills, custom agents e monitoramento. Você sai do fundamentalismo e começa a montar agentes que parecem o seu time.