7.1 Overall Framework Architecture Design

7.1.1 Why Build Your Own Agent Framework

In today's rapidly developing agent technology landscape, there are already many mature Agent frameworks on the market. So why do we still need to build a new framework from scratch?

(1) Rapid Iteration and Limitations of Market Frameworks

The agent field is a rapidly developing area where new concepts emerge constantly. Each framework has its own positioning and understanding of agent design, but the core knowledge points of agents are consistent.

• Complexity of Over-abstraction: Many frameworks introduce numerous abstraction layers and configuration options in pursuit of generality. Taking LangChain as an example, although its chain invocation mechanism is flexible, it has a steep learning curve for beginners, often requiring understanding of many concepts to complete simple tasks.
• Instability from Rapid Iteration: Commercial frameworks frequently change API interfaces to capture market share. Developers often face the frustration of code not running after version upgrades, with maintenance costs remaining high.
• Black-box Implementation Logic: Many frameworks encapsulate core logic too tightly, making it difficult for developers to understand the internal working mechanisms of Agents and lacking deep customization capabilities. When encountering problems, they can only rely on documentation and community support, especially if the community is not active enough, feedback may take a very long time without anyone pushing it forward, affecting subsequent development efficiency.
• Complexity of Dependencies: Mature frameworks often carry a large number of dependency packages, with large installation package sizes, which may cause dependency conflict problems when needing to cooperate with other project code.

(2) Capability Leap from User to Builder

Building your own Agent framework is actually a process of transforming from a "user" to a "builder." The value brought by this transformation is long-term.

• Deep Understanding of Agent Working Principles: By implementing each component hands-on, developers can truly understand the Agent's thinking process, tool invocation mechanisms, and the pros and cons and differences of various design patterns.
• Gaining Complete Control: A self-built framework means complete control over every line of code, allowing precise tuning according to specific needs without being constrained by third-party framework design philosophies.
• Cultivating System Design Capabilities: The framework construction process involves core software engineering skills such as modular design, interface abstraction, and error handling, which are of significant value to developers' long-term growth.

(3) Necessity of Customization Needs and Deep Mastery

In practical applications, the needs for agents vary greatly across different scenarios, often requiring secondary development based on general frameworks.

• Optimization Needs for Specific Domains: Vertical domains such as finance, healthcare, and education often require targeted prompt templates, special tool integration, and customized security strategies.
• Precise Control of Performance and Resources: In production environments, there are strict requirements for response time, memory usage, and concurrent processing capabilities. The "one-size-fits-all" solutions of general frameworks often cannot meet refined needs.
• Transparency Requirements for Learning and Teaching: In our teaching scenario, learners expect to clearly see every step of the agent construction process and understand the working mechanisms of different paradigms, which requires the framework to have high observability and interpretability.

7.1.2 Design Philosophy of HelloAgents Framework

Building a new Agent framework is not about the number of features but whether the design philosophy can truly solve the pain points of existing frameworks. The design of the HelloAgents framework revolves around a core question: How can learners both get started quickly and deeply understand the working principles of Agents?

When you first encounter any mature framework, you may be attracted by its rich features, but you will soon discover a problem: to complete a simple task, you often need to understand more than a dozen different concepts such as Chain, Agent, Tool, Memory, Retriever, etc. Each concept has its own abstraction layer, making the learning curve extremely steep. Although this complexity brings powerful functionality, it also becomes an obstacle for beginners. The HelloAgents framework attempts to find a balance between functional completeness and learning friendliness, forming four core design philosophies.

(1) Balance Between Lightweight and Teaching-Friendly

An excellent learning framework should have complete readability. HelloAgents separates core code by chapters, based on a simple principle: any developer with a certain programming foundation should be able to fully understand the framework's working principles within a reasonable time. In dependency management, the framework adopts a minimalist strategy. Except for OpenAI's official SDK and a few necessary basic libraries, no heavy dependencies are introduced. When encountering problems, we can directly locate the framework's own code without searching for answers in complex dependency relationships.

(2) Pragmatic Choice Based on Standard APIs

OpenAI's API has become an industry standard, and almost all mainstream LLM providers are working hard to be compatible with this interface. HelloAgents chooses to build on this standard rather than reinventing an abstract interface. This decision is mainly motivated by several points. First is the guarantee of compatibility. After mastering the use of HelloAgents, when migrating to other frameworks or integrating it into existing projects, the underlying API invocation logic is completely consistent. Second is the reduction of learning costs. You don't need to learn new conceptual models because all operations are based on standard interfaces you are already familiar with.

(3) Careful Design of Progressive Learning Path

HelloAgents provides a clear learning path. We will save the learning code for each chapter as a historical version that can be downloaded via pip, so there is no need to worry about the cost of using the code, because every core function will be written by yourself. This design allows you to move forward according to your own needs and pace. Each upgrade is natural, without conceptual jumps or understanding gaps. It's worth mentioning that the content of this chapter is also based on the content of the previous six chapters. Similarly, this chapter also lays the framework foundation for subsequent advanced knowledge learning.

(4) Unified "Tool" Abstraction: Everything is a Tool

To thoroughly implement the lightweight and teaching-friendly philosophy, HelloAgents made a key simplification in architecture: except for the core Agent class, everything is Tools. Memory, RAG (Retrieval-Augmented Generation), RL (Reinforcement Learning), MCP (Protocol), and other modules that need to be learned independently in many other frameworks are all uniformly abstracted as a "tool" in HelloAgents. The original intention of this design is to eliminate unnecessary abstraction layers, allowing learners to return to the most intuitive core logic of "agents calling tools," thereby truly achieving the unity of quick start and deep understanding.

7.1.3 Learning Objectives of This Chapter

Let's first look at the core learning content of Chapter 7:

hello-agents/
├── hello_agents/
│   │
│   ├── core/                     # Core framework layer
│   │   ├── agent.py              # Agent base class
│   │   ├── llm.py                # HelloAgentsLLM unified interface
│   │   ├── message.py            # Message system
│   │   ├── config.py             # Configuration management
│   │   └── exceptions.py         # Exception system
│   │
│   ├── agents/                   # Agent implementation layer
│   │   ├── simple_agent.py       # SimpleAgent implementation
│   │   ├── react_agent.py        # ReActAgent implementation
│   │   ├── reflection_agent.py   # ReflectionAgent implementation
│   │   └── plan_solve_agent.py   # PlanAndSolveAgent implementation
│   │
│   ├── tools/                    # Tool system layer
│   │   ├── base.py               # Tool base class
│   │   ├── registry.py           # Tool registration mechanism
│   │   ├── chain.py              # Tool chain management system
│   │   ├── async_executor.py     # Asynchronous tool executor
│   │   └── builtin/              # Built-in tool set
│   │       ├── calculator.py     # Calculator tool
│   │       └── search.py         # Search tool
└──

Before starting to write specific code, we need to first establish a clear architectural blueprint. The architectural design of HelloAgents follows the core principles of "layered decoupling, single responsibility, unified interface," which maintains code organization and facilitates content expansion by chapters.

Quick Start: Installing HelloAgents Framework

To allow readers to quickly experience the complete functionality of this chapter, we provide a directly installable Python package. You can install the version corresponding to this chapter with the following command:

# hello-agents framework code visible link: https://github.com/jjyaoao/helloagents
# Python version needs to be >= 3.10
pip install "hello-agents==0.1.1"

Learning this chapter can be done in two ways:

1. Experiential Learning: Directly install the framework using pip, run example code, and quickly experience various functions
2. Deep Learning: Follow the content of this chapter, implement each component from scratch, and deeply understand the framework's design ideas and implementation details

We recommend adopting the "experience first, then implement" learning path. In this chapter, we provide complete test files. You can rewrite core functions and run tests to verify whether your implementation is correct. This learning method ensures both practicality and learning effectiveness. If you want to deeply understand the framework's implementation details or wish to participate in the framework's development, you can visit this GitHub repository.

Before starting, let's experience building a simple agent using Hello-agents in 30 seconds!

# Configure the LLM API in the .env file in the same-level folder. You can refer to the .env.example in the code folder, or reuse the .env file from previous chapter cases.
from hello_agents import SimpleAgent, HelloAgentsLLM
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Create LLM instance - framework automatically detects provider
llm = HelloAgentsLLM()

# Or manually specify provider (optional)
# llm = HelloAgentsLLM(provider="modelscope")

# Create SimpleAgent
agent = SimpleAgent(
    name="AI Assistant",
    llm=llm,
    system_prompt="You are a helpful AI assistant"
)

# Basic conversation
response = agent.run("Hello! Please introduce yourself")
print(response)

# Add tool functionality (optional)
from hello_agents.tools import CalculatorTool
calculator = CalculatorTool()
# Need to implement MySimpleAgent in 7.4.1 for invocation, subsequent chapters will support this invocation method
# agent.add_tool(calculator)

# Now you can use tools
response = agent.run("Please help me calculate 2 + 3 * 4")
print(response)

# View conversation history
print(f"Number of historical messages: {len(agent.get_history())}")