$ show datawhalechina/hello-agents
This repository is a large-scale educational resource and community showcase for building LLM-powered agents using the custom 'HelloAgents' framework. It is organized as a multi-chapter tutorial (16 chapters) covering agent fundamentals, tool use, memory systems, multi-agent protocols (MCP/A2A/ANP), context engineering, reinforcement learning (SFT→GRPO), and evaluation. Each chapter contains runnable code examples, and the repository also hosts 40+ community-contributed 'Co-creation-projects' that demonstrate real-world agent applications across domains including stock analysis, health record management, academic research, code assistance, game design, and data analysis. The architecture is not a single deployable system but a polyglot collection of independent projects, most following a FastAPI backend + Vue/React frontend pattern, with a shared dependency on the HelloAgents framework core. The primary data flow in each project is: user input → LLM reasoning loop (ReAct/Plan-and-Solve/Reflection) → tool execution (search, database, code execution, APIs) → memory/context update → response generation. External dependencies include OpenAI-compatible LLM APIs, search engines (Tavily, Brave, DuckDuckGo), vector stores (Qdrant, Milvus, Neo4j), and various domain-specific APIs (financial data, academic databases, weather). The codebase serves as both a learning path for agent development and a practical reference for common agent patterns, though quality varies significantly between the polished tutorial chapters and the prototype-level community projects.
The LLM identified 5 files worth highlighting for reuse:
Implements a thread-safe ToolCallTracker that collects tool execution events (start, stream, end, error) and drains them into SSE-formatted payloads. The tracker uses a list-based buffer with drain-and-reset semantics, and each event carries a timestamp, tool name, arguments, and structured result. This pattern is reusable across any agent system that needs to stream tool call progress to a frontend, and it is self-contained with no internal framework dependencies.
Provides a TTL cache with fresh/stale entry semantics and automatic fallback when external API quotas are exhausted. The cache stores entries with timestamps, exposes get_fresh() and get_stale() methods, and supports a 'quota exhausted' mode that returns stale data instead of failing. This pattern is directly reusable in any application that consumes rate-limited external APIs and needs graceful degradation.
A self-contained PDF-to-Markdown extraction pipeline that handles text extraction, broken-line repair (hyphenation), encoding normalization, and structured output. It uses pdfplumber for extraction and applies heuristic post-processing to reconstruct paragraphs and fix common PDF artifacts. This component solves a recurring data engineering problem and can be extracted into any project needing clean text from academic or business PDFs.
A database client that abstracts over libsql (SQLite) and PostgreSQL with automatic retry on locked/busy errors, WAL mode configuration for SQLite, and a context-managed transaction helper. It includes runtime migration logic (ALTER TABLE) and connection pooling. The dual-driver pattern with retry and WAL tuning demonstrates non-obvious database engineering skill and is reusable in any application needing robust local database access.
Implements a secure terminal execution tool that restricts commands to a whitelist (e.g., ls, cat, grep, find, python, pip) and blocks dangerous operations (rm, sudo, su, chmod, etc.). It captures stdout/stderr separately, enforces a timeout, and returns structured results. This pattern is directly reusable in any agent system that needs to grant LLMs controlled shell access without compromising security.