Datawhale Essentials — Building AI Agents from Scratch with HelloAgents

---

Recently, Datawhale launched a content series to help learners systematically get started with AI Agents: Agent Collection.

In earlier articles, we covered the basics of Agents and mainstream frameworks. Starting with this article, we move to a more challenging but valuable goal: building an Agent framework from scratch — HelloAgents.

---

Why Build Your Own Agent Framework?

Although many mature Agent frameworks exist, creating one from scratch offers distinct advantages.

1. Rapid Iteration & Framework Limitations

The Agent field evolves quickly, but existing frameworks have trade-offs:

• Excessive abstraction complexity — Beginners face steep learning curves.
• Instability from rapid iteration — Frequent API changes break implementations.
• Black-box core logic — Deep customization is harder without transparency.
• Complex dependency chains — Heavy installs and potential integration conflicts.

---

2. From User to Builder

Creating your own framework shifts you from user to architect:

• Deep understanding of Agent inner workings.
• Full control over code and design choices.
• Systems design practice in modularity, interfaces, error handling.

---

3. Customization & Mastery

Real-world use cases often demand beyond-generic modifications:

• Domain-specific optimization — Finance, healthcare, education each need tailored prompts, tools, policies.
• Performance/resource management — Tight SLAs in production.
• Transparency in learning/teaching — Highly observable, explainable frameworks aid education.

---

Tip: Combining a self-built framework with distribution platforms like AiToEarn官网 can extend your work from development to monetization. AiToEarn enables AI-driven content creation, simultaneous publishing to Douyin, Kwai, WeChat, Bilibili, Rednote, Facebook, Instagram, LinkedIn, Threads, YouTube, Pinterest, X (Twitter), and analytics/model ranking.

---

Framework Design Philosophy — HelloAgents

Key question:

> How to let beginners start quickly and grasp Agent mechanics in depth?

Many mature frameworks require learning 10+ concepts for simple tasks — steep entry but powerful features. HelloAgents balances completeness with beginner-friendliness through four design principles:

---

1. Lightweight & Teaching-Friendly

• Fully readable code, organized in chapter-based sections.
• Minimal dependencies beyond OpenAI SDK and essentials, for traceability.

---

2. Pragmatic Standard API Use

• Based directly on OpenAI-compatible APIs for industry-standard alignment.
• Compatibility with multiple provider integrations.

---

3. Progressive Learning Path

• Historical versions of instructional code available via `pip`.
• Step-by-step development without conceptual leaps.

---

4. Unified "Tool" Abstraction

• Only two core classes: `Agent` and `Tool`.
• Memory, RAG, RL, protocols—everything treated as a Tool for simpler onboarding.

---

HelloAgents Architecture Overview

hello-agents/
├── hello_agents/
│   ├── core/                     # Core framework
│   │   ├── agent.py               # Agent base class
│   │   ├── llm.py                  # HelloAgentsLLM API wrapper
│   │   ├── message.py              # Messaging system
│   │   ├── config.py               # Configuration
│   │   └── exceptions.py           # Error handling
│   ├── agents/                     # Agent implementations
│   │   ├── simple_agent.py
│   │   ├── react_agent.py
│   │   ├── reflection_agent.py
│   │   └── plan_solve_agent.py
│   ├── tools/                      # Tools
│   │   ├── base.py
│   │   ├── registry.py
│   │   ├── chain.py
│   │   ├── async_executor.py
│   │   └── builtin/
│   │       ├── calculator.py
│   │       └── search.py

Design principles: layered decoupling, single responsibility, unified interfaces.

---

Core Framework Layer — Examples

HelloAgentsLLM: Multi-Provider Capability

Goals:

• Multi-provider support — OpenAI, ModelScope, Zhipu AI, etc.
• Local model integration — VLLM, Ollama for on-prem alternatives.
• Auto-detection from environment variables/base URLs.

Example:

Auto-detect provider by environment variables, then resolve credentials and default endpoints automatically.

---

Message Class

Manages conversation history between user and assistant:

MessageRole = Literal["user", "assistant", "system", "tool"]

class Message(BaseModel):
    content: str
    role: MessageRole
    timestamp: datetime = None
    metadata: Optional[Dict[str, Any]] = None
    ...

• `Literal` enforces valid `role` values.
• Extra fields for logging and extensibility.
• `to_dict()` formats for OpenAI API.

---

Config Class

Centralized configuration management with environment variable overrides.

---

Agent Base Class

Defines common interface via `@abstractmethod run()`, manages conversation history, and integrates with LLM and system prompts.

---

Agent Implementation Layer

HelloAgents contains unified versions of classic paradigms:

• SimpleAgent
• ReActAgent
• ReflectionAgent
• PlanAndSolveAgent
• FunctionCallAgent

All share the same base interface and tool system.

---

Example: SimpleAgent

Provides basic conversation response with optional tool-calling logic:

• Enhance system prompt with tool info.
• Iteratively process LLM output and execute tools if requested.
• History management and streaming support.

---

Integration Idea:

Couple conversational Agents with cross-platform content publishing through AiToEarn for automated generation→publishing→monetization workflows.

---

Tool System Layer

Tools extend Agent functionality. Components:

• Tool base class — standardized run/get_parameters interface.
• ToolRegistry — central discovery, registration, execution.
• ToolParameter — schema for tool arguments.

---

Example Tools

• Calculator Tool — function-based registration for quick math capabilities.
• Advanced Search Tool — class-based integration of Tavily + SerpAPI backends with fault tolerance and unified result formatting.

---

Tool Chains:

Sequence multiple tools for complex tasks, e.g., "search → calculate → summarize".

Async Executor:

Run independent tools concurrently for performance gains.

---

Key Design Principles for Tools

• Single responsibility per tool.
• Consistent interfaces.
• Robust error handling & input validation.
• Asynchronous optimization for concurrent tasks.
• Responsible resource management.

---

Why This Matters for Content Creators

Pairing structured Agent + Tool systems with open-source ecosystems like AiToEarn官网 enables:

• AI Generation using local/cloud models.
• Cross-platform publishing across major networks.
• Analytics & model ranking for optimization.
• Revenue generation in one workflow.

---

Summary

In this guide, we've:

• Built the HelloAgents framework step-by-step.
• Unified multiple Agent paradigms under a clean architecture.
• Designed a flexible Tool system with advanced features.
• Suggested integration paths to global publishing/monetization via AiToEarn.

HelloAgents illustrates that starting simple and expanding gradually produces frameworks that are both educational and production-ready, with clean APIs and maintainable codebases—ready to integrate into larger ecosystems connecting development to global reach.