hello-agents: construir agente IA do zero em 2026 sem LangChain

Cansei de ver README de projeto de agente prometendo “agente em 5 minutos” com meia dúzia de emoji e zero profundidade técnica. O hello-agents é outra categoria de coisa: dezesseis capítulos divididos em cinco partes, com o quarto implementando ReAct, Plan-and-Solve e Reflection na mão, sem import de LangChain, LangGraph ou CrewAI nenhum. Isso me fez abandonar a ideia inicial de tratar o projeto como “mais um tutorial chinês de agente”. O que encontrei foi um material que funciona quase como raio-x de tudo que framework de agente esconde debaixo do capô. O repositório é do Datawhale, comunidade chinesa de educação aberta em dados e IA, está no GitHub como datawhalechina/hello-agents, criado em setembro de 2025, com tópicos marcados como agent, llm, rag e tutorial.

O que o hello-agents realmente ensina (e por que “do zero” aqui não é força de expressão)

O título original do projeto é 《从零开始构建智能体》, que traduz literalmente para “construindo agentes do zero”. E pelo README, essa não é força de expressão de marketing: o próprio texto de introdução do projeto diz que existem duas linhagens de “agente” no mercado. Uma orientada a fluxo (Dify, Coze, n8n, onde o LLM é só mais um nó de processamento) e outra “AI native”, em que o modelo de fato dirige o comportamento. O curso declara abertamente que quer te levar a construir a segunda, atravessando a superfície dos frameworks até os princípios centrais.

Na prática isso significa que o capítulo 7 do curso ensina a construir seu próprio framework de agente, batizado de HelloAgents, usando a API nativa da OpenAI, sem wrapper pronto. Isso é diferente de pegar o quickstart do LangChain e trocar o prompt. É escrever o laço de decisão, o parsing de resposta do modelo e a orquestração de ferramentas com as próprias mãos antes de qualquer abstração pronta aparecer no caminho. Conferi o notebook desse capítulo no próprio repositório (o código vem comentado em chinês, mas a lógica do laço de execução é legível independente de idioma) e a implementação realmente evita qualquer biblioteca de agente, só a API crua de chat completion.

Capítulo por capítulo: o que cada módulo tira da caixa-preta de um framework pronto

Mapear a estrutura ajuda, porque ela não é aleatória: segue a ordem que você normalmente não segue quando aprende framework primeiro. A tabela de conteúdo do repositório tem cinco partes.

A Parte 1 (capítulos 1 a 3) cobre fundamentos: definição de agente, história do campo (do simbolismo até LLM) e bases de LLM, incluindo Transformer e limitações do modelo. A Parte 2 (capítulos 4 a 7) é o miolo técnico: capítulo 4 implementa ReAct, Plan-and-Solve e Reflection manualmente; capítulo 5 passa por plataformas low-code (Coze, Dify, n8n); capítulo 6, só aí, introduz frameworks prontos como AutoGen, AgentScope e LangGraph; o capítulo 7 fecha construindo um framework próprio do zero.

A Parte 3 (capítulos 8 a 12) avança para tópicos que normalmente só aparecem quando você já quebrou a cara em produção: memória e retrieval (RAG), engenharia de contexto, protocolos de comunicação entre agentes (MCP, A2A, ANP), treinamento com Agentic-RL (de SFT a GRPO) e avaliação de desempenho. A Parte 4 (capítulos 13 a 15) sai da teoria para projetos: um assistente de viagem com MCP e multiagentes, um agente de pesquisa profunda inspirado em DeepResearch, e uma “cidade cibernética” simulando dinâmica social com agentes. A Parte 5 (capítulo 16) é o projeto de conclusão, onde você monta sua própria aplicação multiagente do zero.

O ponto que separa isso de um curso qualquer é a ordem: framework pronto só aparece no capítulo 6, depois que você já implementou o raciocínio na mão no capítulo 4. É o oposto do caminho que a maioria dos devs faz, abrir o LangChain primeiro e conhecer ReAct só como nome de uma classe.

ReAct na mão: o loop que todo framework esconde até ele travar em produção

ReAct, o padrão “pensa, age, observa, repete” que virou praticamente sinônimo de “agente”, costuma vir implementado numa classe do LangChain, ou num node do LangGraph. Você importa, passa um prompt, pronto. O problema aparece quando esse agente entra num loop infinito de chamada de ferramenta: pede a mesma busca cinco vezes seguidas, ou alterna entre duas ações sem nunca produzir uma resposta final. Nessas horas o dev abre o log, vê um amontoado de JSON de tool call repetido, e não tem a menor ideia de onde intervir, porque nunca viu o parsing por dentro, só sabe que “o agente travou”.

Quem implementou o loop ReAct manualmente, como propõe o capítulo 4 do hello-agents, sabe exatamente onde esse loop vive: é o ponto em que a saída do modelo é interpretada como “ação” versus “resposta final”, e geralmente trava porque o critério de parada (um token, uma palavra-chave, um formato específico) não bateu com o que o modelo devolveu daquela vez. Saber isso na mão muda o debug de “reiniciar e torcer” para “olhar o prompt de parada e o parser de decisão”.

Tool calling sem biblioteca: onde nasce a maioria dos bugs que ninguém sabe explicar

Function calling, ou tool calling, é provavelmente a parte mais mastigada por qualquer framework de agente. O LangChain valida o schema da ferramenta, tenta corrigir formato malformado, reempacota erro de parsing em exceção genérica. Ótimo até quebrar. É bem comum o modelo devolver um JSON levemente errado (aspas trocadas, campo faltando, tipo incompatível) e a aplicação simplesmente estourar uma exceção sem contexto nenhum sobre o que realmente aconteceu na resposta do LLM.

O capítulo 7, ao propor construir seu próprio framework usando API nativa da OpenAI, implica lidar com esse parsing na mão: extrair a chamada de função da resposta bruta do modelo, validar contra o schema esperado, decidir o que fazer quando o formato não bate. Isso não é curiosidade acadêmica, é exatamente o ponto onde a maioria dos bugs inexplicáveis de agente em produção nasce, e também o ponto que o engenheiro que só usou framework pronto não sabe nomear quando precisa explicar pro time por que o agente de atendimento parou de funcionar às 3 da manhã.

Memória e RAG no curso: a diferença entre copiar código de exemplo e entender ciclo de vida de estado

O capítulo 8 do hello-agents trata de memória e retrieval, cobrindo sistemas de memória, RAG e armazenamento. É um tópico onde a confusão é enorme na comunidade: muita gente copia um bloco de código de memória de um framework, tipo um ConversationBufferMemory ou equivalente, sem entender se aquele estado é persistido entre sessões, descartado a cada reinício, ou truncado silenciosamente quando estoura o limite de contexto. O efeito prático é um agente que esquece o que o usuário disse cinco mensagens atrás, e ninguém no time sabe dizer se é bug de memória, limite de janela de contexto ou erro de retrieval no vetor store.

O que diferencia o módulo do hello-agents, pela estrutura documentada no sumário, é separar isso em dois capítulos distintos: memória e retrieval (capítulo 8) e engenharia de contexto (capítulo 9), tratada como compreensão situacional para interações contínuas. Essa separação já sugere algo que a maioria dos wrappers de framework borra: memória de longo prazo e contexto de curto prazo são problemas diferentes, com ciclos de vida diferentes. Tratar os dois como a mesma coisa é receita pra bug difícil de reproduzir.

As barreiras reais: idioma, maturidade do repositório e o que falta pra virar referência em PT-BR

Agora a parte honesta. O hello-agents é majoritariamente em chinês. O README tem versão em inglês (README_EN.md), mas o conteúdo dos dezesseis capítulos, inclusive o código-fonte e os comentários dos notebooks, está em chinês. Não existe tradução para português, nem indicação de que exista uma vindo. Isso coloca qualquer leitor brasileiro diante da mesma decisão chata que aparece toda vez que um bom material educacional nasce fora do eixo inglês-americano: traduzir trecho por trecho com apoio de tradutor automático e aceitar que vai perder nuance técnica, ou esperar uma maturação que pode nunca vir.

A licença do repositório aparece como NOASSERTION no GitHub (sem uma licença clara declarada), o que importa se você pensa em adaptar ou redistribuir o material, não só em ler. E o projeto é recente, criado em setembro de 2025; mesmo com todos os dezesseis capítulos marcados como concluídos na tabela de conteúdo, “recente” e “sem tradução oficial” significa que ele ainda não é um material estabelecido como referência comparável a, digamos, a documentação consolidada de um framework maduro. É um curso estruturado e ambicioso, não uma enciclopédia revisada por anos de comunidade.

Pra quem vale estudar isso antes de abrir o próximo framework de agente

Minha leitura, com base no que a estrutura, o README e o notebook do capítulo 7 mostram: isso vale mais para quem já apanhou de agente em produção do que para quem está começando do zero absoluto. Se você é dev júnior que nunca tocou em LLM, o caminho mais suave ainda é começar por algo em português ou inglês com comunidade ativa de suporte. O choque de ler código comentado em chinês traduzido na mão pode ser grande demais como primeiro contato.

Mas se você já usa LangChain, CrewAI ou AutoGen no dia a dia e nunca parou pra implementar o loop ReAct ou o parsing de tool call sem lib nenhuma, o capítulo 4 e o capítulo 7 do hello-agents valem o esforço de tradução manual, mesmo que você nunca mais escreva um agente sem framework depois disso. Se seu trabalho inclui sistemas de memória de agente e você nunca separou claramente retrieval de contexto de curto prazo, os capítulos 8 e 9 preenchem exatamente essa lacuna conceitual. Quem só quer prototipar rápido para validar uma ideia de produto, honestamente, não precisa disso agora: framework pronto resolve mais rápido, e entender o porquê por trás dele pode vir depois, quando o protótipo virar sistema de verdade e começar a quebrar.

Framework de agente eu uso, recomendo e continuo usando no dia a dia. Mas tratar “saber LangChain” como sinônimo de “saber construir agente de IA” é o mesmo erro de achar que saber dirigir com câmbio automático ensina como funciona uma embreagem. O hello-agents não substitui o framework. Ele te dá o motivo técnico pra parar de só confiar nele de olhos fechados.

Repositório: github.com/datawhalechina/hello-agents