HelloAgents V0.2.8 Release Notes

📅 Release Date: 2025-10-26
📦 Package: pip install hello-agents>=0.2.8
🔗 GitHub: https://github.com/jjyaoao/HelloAgents
📚 Documentation: https://github.com/jjyaoao/HelloAgents/tree/main/docs

🎯 Overview

HelloAgents V0.2.8 introduces enhanced tool observability and flexible LLM provider support, enabling developers to build more sophisticated agentic applications with better monitoring and deployment flexibility. This release implements key features from Chapter 14 (Deep Research Agent), providing improved tool call tracking and custom provider integration.

✨ Core Features

• 🔍 ToolAwareSimpleAgent: Enhanced SimpleAgent with tool call monitoring and event callbacks
• 🌐 Custom Provider Support: Connect to any OpenAI-compatible API endpoint
• 🛠️ SearchTool Enhancements: Improved multi-backend search capabilities
• 📊 Tool Call Tracking: Built-in tool execution history and event listeners
• 🔄 Backward Compatible: All existing code continues to work seamlessly

🔧 Installation & Upgrade

New Installation

# Basic installation
pip install hello-agents>=0.2.8

# With search functionality
pip install hello-agents[search]

# With all features
pip install hello-agents[all]

Upgrade from Previous Versions

# Upgrade to latest version
pip install --upgrade hello-agents

# Or specify version
pip install hello-agents==0.2.8

Verify Installation

import hello_agents
print(hello_agents.__version__)  # Should print: 0.2.8

🆕 What's New

1. ToolAwareSimpleAgent - Tool Call Monitoring ✨

Overview: A new agent class that extends SimpleAgent with tool call observation capabilities, perfect for building applications that need to track and respond to tool executions.

Key Features:

• Event Callbacks: Register listeners for tool call events
• Execution History: Automatic tracking of all tool calls
• Real-time Monitoring: React to tool executions as they happen
• Zero Overhead: Same performance as SimpleAgent when callbacks not used

Quick Start:

from hello_agents import ToolAwareSimpleAgent, HelloAgentsLLM
from hello_agents.tools import SearchTool, ToolRegistry

# Create LLM and tools
llm = HelloAgentsLLM(model="gpt-4")
search_tool = SearchTool(backend="tavily")

# Create tool registry
registry = ToolRegistry()
registry.register_tool(search_tool)

# Define callback function
def on_tool_call(tool_name, arguments, result):
    print(f"🔧 Tool Called: {tool_name}")
    print(f"📥 Arguments: {arguments}")
    print(f"📤 Result: {result[:100]}...")  # First 100 chars

# Create ToolAwareSimpleAgent with callback
agent = ToolAwareSimpleAgent(
    name="Research Assistant",
    system_prompt="You are a helpful research assistant.",
    llm=llm,
    tool_registry=registry,
    tool_call_callback=on_tool_call  # Register callback
)

# Use agent normally
response = agent.run("What is the latest news about AI?")

Output:

🔧 Tool Called: search
📥 Arguments: {'input': 'latest AI news', 'backend': 'tavily'}
📤 Result: 🔍 Search Results: [1] OpenAI releases GPT-5...

Use Cases:

• Progress Tracking: Show users what the agent is doing
• Debugging: Monitor tool calls during development
• Logging: Record all tool executions for analysis
• UI Updates: Update frontend in real-time (e.g., Chapter 14 Deep Research UI)

Advanced Example - Multiple Callbacks:

# Track tool call history
tool_history = []

def track_history(tool_name, arguments, result):
    tool_history.append({
        "tool": tool_name,
        "args": arguments,
        "result": result,
        "timestamp": datetime.now()
    })

def log_to_file(tool_name, arguments, result):
    with open("tool_calls.log", "a") as f:
        f.write(f"{datetime.now()}: {tool_name}({arguments})\n")

# Combine callbacks
def combined_callback(tool_name, arguments, result):
    track_history(tool_name, arguments, result)
    log_to_file(tool_name, arguments, result)

agent = ToolAwareSimpleAgent(
    name="Monitored Agent",
    llm=llm,
    tool_registry=registry,
    tool_call_callback=combined_callback
)

2. Custom Provider Support - Flexible LLM Integration 🌐

Overview: HelloAgentsLLM now supports custom provider type, allowing you to connect to any OpenAI-compatible API endpoint without predefined provider configurations.

Key Features:

• Universal Compatibility: Works with any OpenAI-compatible API
• Flexible Configuration: Custom base_url and api_key
• No Code Changes: Same HelloAgentsLLM interface
• Perfect for: Local deployments, custom endpoints, proxy services

Quick Start:

from hello_agents import HelloAgentsLLM

# Connect to custom endpoint
llm = HelloAgentsLLM(
    provider="custom",
    model="your-model-name",
    base_url="https://your-api-endpoint.com/v1",
    api_key="your-api-key"
)

# Use normally
response = llm.chat("Hello, world!")
print(response)

Common Use Cases:

1. Local LLM Deployment (Ollama):

llm = HelloAgentsLLM(
    provider="custom",
    model="llama3.2",
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # Ollama doesn't require real key
)

2. LMStudio:

llm = HelloAgentsLLM(
    provider="custom",
    model="qwen-qwq-32b",
    base_url="http://localhost:1234/v1",
    api_key="lm-studio"
)

3. Custom Proxy Service:

llm = HelloAgentsLLM(
    provider="custom",
    model="gpt-4",
    base_url="https://your-proxy.com/v1",
    api_key="your-proxy-key"
)

4. Enterprise Internal API:

llm = HelloAgentsLLM(
    provider="custom",
    model="company-llm-v1",
    base_url="https://internal-api.company.com/v1",
    api_key=os.getenv("COMPANY_API_KEY")
)

Environment Variable Configuration:

# .env file
LLM_PROVIDER=custom
LLM_MODEL_ID=your-model-name
LLM_BASE_URL=https://your-api-endpoint.com/v1
LLM_API_KEY=your-api-key

# Load from environment
from hello_agents import HelloAgentsLLM

llm = HelloAgentsLLM()  # Automatically loads from .env

Supported Providers (Updated):

3. SearchTool File Reorganization 📁

Overview: SearchTool has been renamed from search.py to search_tool.py for better consistency with other tool naming conventions.

Changes:

• ✅ File renamed: search.py → search_tool.py
• ✅ All imports updated automatically
• ✅ Public API unchanged
• ✅ Backward compatible

Import Paths (No changes needed):

# All these still work
from hello_agents.tools import SearchTool
from hello_agents import SearchTool
from hello_agents.tools.builtin.search_tool import SearchTool  # New path

Why This Change?:

• Consistent naming: search_tool.py, note_tool.py, rag_tool.py
• Better code organization
• Clearer module structure

🏗️ Architecture Improvements

Tool System Enhancements

Before (V0.2.7):

SimpleAgent
├── Tool Registry
└── Tools (no observability)

After (V0.2.8):

ToolAwareSimpleAgent
├── Tool Registry
├── Tools
└── Tool Call Callbacks
    ├── Event Listeners
    ├── Execution History
    └── Real-time Monitoring

LLM Provider System

Before (V0.2.7):

# Limited to predefined providers
SUPPORTED_PROVIDERS = [
    "modelscope", "openai", "deepseek",
    "dashscope", "kimi", "zhipu",
    "ollama", "vllm"
]

After (V0.2.8):

# Now includes custom provider
SUPPORTED_PROVIDERS = [
    "modelscope", "openai", "deepseek",
    "dashscope", "kimi", "zhipu",
    "ollama", "vllm", "custom"  # ✨ New
]

📚 Real-World Example: Deep Research Agent (Chapter 14)

Overview

The Deep Research Agent from Chapter 14 demonstrates the power of V0.2.8 features, combining ToolAwareSimpleAgent with custom provider support for a production-ready research assistant.

Architecture:

Deep Research Agent
├── Frontend (Vue 3)
│   └── Real-time Progress Display
│
├── Backend (FastAPI)
│   ├── DeepResearchAgent (ToolAwareSimpleAgent)
│   ├── SearchTool (Multi-backend)
│   ├── NoteTool (Progress tracking)
│   └── SSE Streaming
│
└── LLM (Custom Provider)
    ├── Ollama (Local)
    ├── LMStudio (Local)
    └── Cloud APIs (OpenAI, DeepSeek, etc.)

Key Features Enabled by V0.2.8:

1. Tool Call Monitoring: Track search and note-taking in real-time
2. Custom Provider: Support local and cloud LLMs seamlessly
3. Progress Streaming: Update UI as research progresses

Code Snippet:

from hello_agents import ToolAwareSimpleAgent, HelloAgentsLLM
from hello_agents.tools import SearchTool, NoteTool, ToolRegistry

# Custom provider for local LLM
llm = HelloAgentsLLM(
    provider="custom",
    model="qwen-qwq-32b",
    base_url="http://localhost:1234/v1",
    api_key="lm-studio"
)

# Create tools
search_tool = SearchTool(backend="hybrid")
note_tool = NoteTool(workspace="./notes")

# Register tools
registry = ToolRegistry()
registry.register_tool(search_tool)
registry.register_tool(note_tool)

# Tool call callback for progress tracking
def on_tool_call(tool_name, arguments, result):
    # Send...

update dependency, Fixed numpy dependency error caused by bfcl.

add builder in chapter9.
fix import error in chapter9.

• NoteTool (hello_agents/tools/builtin/note_tool.py)：结构化笔记工具，支持智能体进行持久化记忆管理
• TerminalTool (hello_agents/tools/builtin/terminal_tool.py)：终端工具，支持智能体进行文件系统操作和即时上下文检索

for chapter9

HelloAgents V0.2.5 Release Notes

📅 Release Date: 2025-10-18
📦 Package: pip install hello-agents[rl]
🔗 GitHub: https://github.com/jjyaoao/HelloAgents
📚 Documentation: https://github.com/jjyaoao/HelloAgents/tree/main/docs/chapter11

🎯 Overview

HelloAgents V0.2.5 introduces a comprehensive Agentic Reinforcement Learning (RL) System, enabling developers to train and fine-tune language models using state-of-the-art RL algorithms. This release implements a complete RL training pipeline according to Chapter 11 architecture, providing a unified toolkit for SFT, GRPO, and distributed training.

✨ Core Features

• 🎓 SFT (Supervised Fine-Tuning): Train models on instruction-following tasks with LoRA support
• 🚀 GRPO (Group Relative Policy Optimization): Simplified PPO without Value Model for efficient RL training
• 🎯 Custom Reward Functions: Accuracy, length penalty, and step-based rewards
• 🛠️ Unified Tool Interface: RLTrainingTool fully integrated with HelloAgents framework
• 📊 Distributed Training: Multi-GPU and multi-node support via Accelerate and DeepSpeed
• 🔄 Monitoring Integration: Wandb and TensorBoard support with detailed logging
• 📦 Simplified Imports: Direct access from hello_agents.rl layer
• 🔄 Backward Compatible: All existing code continues to work

🔧 Installation & Dependencies

Installation

# With RL support
pip install hello-agents[rl]

# Or install manually
pip install hello-agents
pip install trl transformers datasets peft accelerate

Optional Dependencies

# For distributed training
pip install deepspeed

# For monitoring
pip install wandb tensorboard

Dependencies

Environment Configuration

API Keys (Optional for model download):

# HuggingFace Token (for gated models)
HUGGINGFACE_TOKEN="hf_xxx"

# Wandb API Key (for experiment tracking)
WANDB_API_KEY="xxx"

🏗️ RL Training Architecture

Three-Layer RL System (Chapter 11 Design)

Agentic RL Training Architecture
├── Application Layer
│   └── RLTrainingTool - Unified RL training tool wrapper
│
├── Training Layer
│   ├── SFT (Supervised Fine-Tuning)
│   │   ├── SFTTrainerWrapper - TRL SFTTrainer wrapper
│   │   ├── SFT Dataset - Instruction-following dataset
│   │   ├── LoRA Configuration - Parameter-efficient fine-tuning
│   │   └── Training Callbacks - Detailed logging and monitoring
│   │
│   ├── GRPO (Group Relative Policy Optimization)
│   │   ├── GRPOTrainerWrapper - TRL GRPOTrainer wrapper
│   │   ├── GRPO Dataset - Prompt-based dataset
│   │   ├── Reward Functions - Accuracy, length, step-based
│   │   └── KL Divergence Control - Policy regularization
│   │
│   └── Distributed Training
│       ├── DDP - Data Parallel (2-8 GPUs)
│       ├── DeepSpeed ZeRO-2 - Optimizer state sharding
│       ├── DeepSpeed ZeRO-3 - Full model sharding
│       └── Multi-Node - Cluster training support
│
└── Data Layer
    ├── GSM8K - Grade School Math 8K dataset
    ├── UltraFeedback - Preference learning dataset
    └── Custom Datasets - User-defined datasets

🎓 SFT (Supervised Fine-Tuning)

Overview

SFT trains models to follow instructions and learn task-specific formats. HelloAgents provides a complete SFT implementation with LoRA support for efficient training.

Key Features:

• LoRA Support: Train only 0.1% of parameters with minimal quality loss
• GSM8K Dataset: 7,473 math problems for training
• Automatic Formatting: Chat template handling (Qwen, Llama, etc.)
• Progress Tracking: Detailed logging with epoch/step/loss/LR
• Model Saving: Automatic checkpoint saving and merging

Quick Start

from hello_agents.tools import RLTrainingTool

# Create RL training tool
rl_tool = RLTrainingTool()

# Run SFT training
result = rl_tool.run({
    "action": "train",
    "algorithm": "sft",
    "model_name": "Qwen/Qwen3-0.6B",
    "output_dir": "./models/sft_model",
    "max_samples": 100,  # Use 100 samples for quick test
    "num_epochs": 3,
    "batch_size": 4,
    "use_lora": True,  # Enable LoRA
    "use_tensorboard": True,
})

print(f"Training completed! Model saved to: {result['output_dir']}")

Training Output

Epoch 1/3 | Step 10/75 | Loss: 2.3456 | LR: 4.5e-05
Epoch 1/3 | Step 20/75 | Loss: 1.8234 | LR: 4.0e-05
Epoch 1/3 | Step 25/75 | Loss: 1.6543 | LR: 3.8e-05
✓ Epoch 1/3 completed | Average Loss: 1.7234

Epoch 2/3 | Step 35/75 | Loss: 1.2345 | LR: 3.5e-05
...

LoRA Configuration

# Default LoRA config (optimized for Qwen models)
{
    "lora_r": 16,              # Rank
    "lora_alpha": 32,          # Alpha (scaling factor)
    "lora_dropout": 0.05,      # Dropout
    "lora_target_modules": ["q_proj", "v_proj"]  # Target modules
}

# Trainable parameters: ~0.1% of total
# Memory usage: ~50% of full fine-tuning
# Training speed: ~2x faster

🚀 GRPO (Group Relative Policy Optimization)

Overview

GRPO is a simplified PPO algorithm that doesn't require a separate Value Model. It uses group-relative rewards for efficient policy optimization, making it ideal for Agentic RL scenarios.

Key Features:

• No Value Model: Simpler architecture, faster training
• Group Relative Rewards: Compare within mini-batches for stable learning
• Custom Reward Functions: Accuracy, length penalty, step-based rewards
• KL Divergence Control: Prevent policy from deviating too far from reference
• Math Reasoning: Optimized for GSM8K-style math problems

Quick Start

from hello_agents.tools import RLTrainingTool

# Create RL training tool
rl_tool = RLTrainingTool()

# Run GRPO training
result = rl_tool.run({
    "action": "train",
    "algorithm": "grpo",
    "model_name": "Qwen/Qwen3-0.6B",
    "output_dir": "./models/grpo_model",
    "max_samples": 100,
    "num_epochs": 2,
    "batch_size": 2,
    "reward_type": "accuracy",  # Use accuracy reward
    "use_lora": True,
    "use_tensorboard": True,
})

print(f"GRPO training completed! Model saved to: {result['output_dir']}")

Training Output

Epoch 1/2 | Step 10/50 | Loss: 0.8234 | Reward: 0.45 | KL: 0.023
Epoch 1/2 | Step 20/50 | Loss: 0.6543 | Reward: 0.62 | KL: 0.018
Epoch 1/2 | Step 25/50 | Loss: 0.5432 | Reward: 0.71 | KL: 0.015
✓ Epoch 1/2 completed | Average Reward: 0.68 | Average KL: 0.019

Epoch 2/2 | Step 35/50 | Loss: 0.4321 | Reward: 0.78 | KL: 0.012
...

Reward Functions

# Accuracy reward
reward = 1.0 if prediction == ground_truth else 0.0

# Length penalty reward
base_reward = accuracy_reward
length_penalty = max(0, (len(prediction) - target_length) / target_length)
reward = base_reward - 0.1 * length_penalty

# Step reward
reward = accuracy_reward + 0.1 * num_reasoning_steps

📊 Distributed Training

Overview

When data and model size grow, single-GPU training becomes too slow. HelloAgents supports multi-GPU and multi-node distributed training via Accelerate and DeepSpeed, with zero code changes required.

Key Features:

• DDP (Data Parallel): Simple multi-GPU training (2-8 GPUs)
• DeepSpeed ZeRO-2: Optimizer state sharding (~30% memory savings)
• DeepSpeed ZeRO-3: Full model sharding (~50% memory savings)
• Multi-Node: Cluster training support
• Zero Code Changes: Same training code works for all configurations

Distributed Training Methods

Quick St...

Fix some bug for chapter13. The function is unchanged.

HelloAgents V0.2.3 Release Notes

📅 Release Date: 2025-10-11
📦 Package: pip install hello-agents[evaluation]
🔗 GitHub: https://github.com/jjyaoao/HelloAgents
📚 Documentation: https://github.com/jjyaoao/HelloAgents/tree/main/docs/chapter12

🎯 Overview

HelloAgents V0.2.3 introduces a comprehensive Agent Performance Evaluation System, enabling developers to systematically assess agent capabilities across multiple dimensions. This release implements three major evaluation benchmarks according to Chapter 12 architecture, providing a complete toolkit for measuring and improving agent performance.

✨ Core Features

• 🔧 BFCL (Berkeley Function Calling Leaderboard): Evaluate tool/function calling capabilities with AST matching
• 🤝 GAIA (General AI Assistants): Assess general AI assistant capabilities with multi-level difficulty
• 📊 Data Generation Evaluation: Measure generated data quality using LLM Judge and Win Rate methods
• 🛠️ Unified Tool Interface: BFCLEvaluationTool, GAIAEvaluationTool, LLMJudgeTool, WinRateTool fully integrated
• 📦 Simplified Imports: Direct access from hello_agents.evaluation layer
• 🔄 Backward Compatible: All existing code continues to work

🔧 Installation & Dependencies

Installation

# With evaluation support
pip install hello-agents[evaluation]

Dependencies

Environment Configuration

API Keys (Required for evaluation):

# OpenAI API (for GPT-4o judge model)
OPENAI_API_KEY="sk-xxx"

# ModelScope API (for Qwen models)
MODELSCOPE_API_KEY="xxx"

🏗️ Evaluation Architecture

Three-Layer Evaluation System (Chapter 12 Design)

Agent Performance Evaluation Architecture
├── Application Layer
│   ├── BFCLEvaluationTool - BFCL evaluation tool wrapper
│   ├── GAIAEvaluationTool - GAIA evaluation tool wrapper
│   ├── LLMJudgeTool - LLM Judge evaluation tool
│   └── WinRateTool - Win Rate evaluation tool
│
├── Evaluation Layer
│   ├── BFCL (Berkeley Function Calling Leaderboard)
│   │   ├── BFCLDataset - Dataset loader (7 categories, 2000+ samples)
│   │   ├── BFCLEvaluator - AST-based evaluation engine
│   │   ├── BFCLMetrics - Accuracy and category metrics
│   │   └── AST Matcher - Abstract Syntax Tree matching algorithm
│   │
│   ├── GAIA (General AI Assistants)
│   │   ├── GAIADataset - Dataset loader (3 levels, 466 samples)
│   │   ├── GAIAEvaluator - Quasi Exact Match evaluation
│   │   ├── GAIAMetrics - Level-based performance metrics
│   │   └── Quasi Exact Match - Flexible answer matching algorithm
│   │
│   └── Data Generation Evaluation
│       ├── AIDataset - AIME dataset loader (900+ problems)
│       ├── LLMJudgeEvaluator - Multi-dimensional quality assessment
│       ├── WinRateEvaluator - Pairwise comparison evaluation
│       └── Human Verification UI - Gradio-based manual verification
│
└── Data Layer
    ├── BFCL Data - Local or HuggingFace datasets
    ├── GAIA Data - HuggingFace datasets (gaia-benchmark/GAIA)
    └── AIME Data - HuggingFace datasets (TianHongZXY/aime-1983-2025, math-ai/aime25)

🔧 BFCL (Berkeley Function Calling Leaderboard)

Overview

BFCL evaluates an agent's ability to correctly call functions/tools. HelloAgents provides a complete BFCL implementation with support for all official categories and AST-based matching.

Key Features:

• 7 Evaluation Categories: simple_python, simple_java, simple_javascript, multiple, parallel, parallel_multiple, irrelevance
• AST Matching: Intelligent matching that ignores parameter order and format differences
• Official Integration: Compatible with BFCL official evaluation tool
• Auto Report Generation: Markdown reports with visualizations
• 2000+ Test Samples: Comprehensive coverage of function calling scenarios

Evaluation Categories

Quick Start

from hello_agents import SimpleAgent, HelloAgentsLLM
from hello_agents.tools import BFCLEvaluationTool

# Create agent
agent = SimpleAgent(name="TestAgent", llm=HelloAgentsLLM())

# Create evaluation tool
bfcl_tool = BFCLEvaluationTool()

# Run evaluation (auto-generates report)
results = bfcl_tool.run(
    agent=agent,
    category="simple_python",
    max_samples=5,
    run_official_eval=True,  # Run BFCL official evaluation
    model_name="Qwen/Qwen3-8B"
)

print(f"Accuracy: {results['overall_accuracy']:.2%}")
# Report auto-generated to: evaluation_reports/bfcl_report_{timestamp}.md

Advanced Features

Custom Evaluation:

from hello_agents.evaluation import BFCLDataset, BFCLEvaluator

# Load dataset
dataset = BFCLDataset(category="multiple")

# Create evaluator
evaluator = BFCLEvaluator(dataset=dataset, category="multiple")

# Evaluate
results = evaluator.evaluate(agent, max_samples=10)

# Export to BFCL format
evaluator.export_to_bfcl_format(results, "results.json")

🤝 GAIA (General AI Assistants)

Overview

GAIA evaluates an agent's general problem-solving capabilities across three difficulty levels. HelloAgents integrates the official GAIA benchmark with automatic result export.

Key Features:

• 3 Difficulty Levels: Level 1 (simple), Level 2 (medium), Level 3 (hard)
• 466 Real-World Tasks: Diverse problem types requiring multi-step reasoning
• Quasi Exact Match: Flexible answer matching algorithm
• Official Submission: Auto-generate JSONL files for HuggingFace leaderboard
• Multi-Modal Support: Text, files, and images

Difficulty Levels

Quick Start

from hello_agents import SimpleAgent, HelloAgentsLLM
from hello_agents.tools import GAIAEvaluationTool

# Create agent
agent = SimpleAgent(name="TestAgent", llm=HelloAgentsLLM())

# Create evaluation tool
gaia_tool = GAIAEvaluationTool()

# Run evaluation (auto-generates report and submission guide)
results = gaia_tool.run(
    agent=agent,
    level=1,  # Level 1 (simple tasks)
    max_samples=5,
    export_results=True,  # Export GAIA format
    generate_report=True  # Generate Markdown report
)

print(f"Exact Match Rate: {results['exact_match_rate']:.2%}")
# Report: evaluation_reports/gaia_report_{timestamp}.md
# Submission: evaluation_results/gaia_official/gaia_level1_result_{timestamp}.jsonl

Submission to GAIA Leaderboard

# Auto-generated submission guide
# File: evaluation_results/gaia_official/SUBMISSION_GUIDE_{timestamp}.md

# Steps:
# 1. Visit: https://huggingface.co/spaces/gaia-benchmark/leaderboard
# 2. Upload: gaia_level1_result_{timestamp}.jsonl
# 3. Fill model information
# 4. Submit and wait for results

📊 Data Generation Evaluation

Overview

Evaluate the quality of AI-generated data (e.g., AIME math problems) using two complementary methods: LLM Judge (absolute quality) and Win Rate (relative quality).

Key Features:

• LLM Judge: Multi-dimensional quality assessment (Correctness, Clarity, Difficulty Match, Completeness)
• Win Rate: Pairwise comparison against reference data (AIME 2025)
• Human Verification: Gradio web UI for manual verification
• Comprehensive Reports: Detailed Markdown reports with statistics
• AIME Dataset: 900+ reference problems from 1983-2025

Evaluation Methods

Quick Start - LLM Judge

from hello_agents.tools import LLMJudgeTool
from hello_agents import HelloAgentsLLM

# Create LLM Judge tool
llm = HelloAgentsLLM()
llm_judge_tool = LLMJudgeTool(llm=llm)

# Run e...

HelloAgents V0.2.2 Release Notes

📅 Release Date: 2025-10-11
📦 Package: pip install hello-agents[evaluation]
🔗 GitHub: https://github.com/jjyaoao/HelloAgents
📚 Documentation: https://github.com/jjyaoao/HelloAgents/tree/main/docs/chapter12

🎯 Overview

HelloAgents V0.2.2 introduces fix some bug build on V0.2.1

📞 Support

• GitHub: https://github.com/jjyaoao/HelloAgents
• Documentation: https://github.com/jjyaoao/HelloAgents/tree/main/docs/chapter12
• Email: jjyaoao@126.com
• Datawhale: https://github.com/datawhalechina/Hello-Agents

Happy Evaluating with HelloAgents Evaluation System! 🚀✨

HelloAgents V0.2.1 Release Notes

📅 Release Date: 2025-10-9
📦 Package: pip install hello-agents[protocols]
🔗 GitHub: https://github.com/jjyaoao/HelloAgents
📚 Documentation: https://github.com/jjyaoao/HelloAgents/tree/main/docs/api/protocols

🎯 Overview

HelloAgents V0.2.1 introduces comprehensive Agent Communication Protocol support, enabling agents to interact with external tools, collaborate with other agents, and participate in large-scale agent networks. This release implements three major protocols according to Chapter 10 architecture, providing a complete toolkit for building modern multi-agent systems.

✨ Core Features

• 🔧 MCP (Model Context Protocol): Complete client/server implementation with 5 transport modes
• 🤝 A2A (Agent-to-Agent Protocol): Official SDK integration for agent collaboration
• 🌐 ANP (Agent Network Protocol): Service discovery and network management
• 🛠️ Unified Tool Interface: MCPTool, A2ATool, ANPTool fully integrated with HelloAgents framework
• 📦 Simplified Imports: Direct access from hello_agents.protocols layer
• 🔄 Backward Compatible: All existing code continues to work

🔧 Installation & Dependencies

Installation

# With A2A protocol support
pip install hello-agents[protocols]

Dependencies

Environment Configuration

MCP Server Environment Variables (Auto-detected):

# GitHub Server
GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxx"

# Slack Server
SLACK_BOT_TOKEN="xoxb-xxx"
SLACK_TEAM_ID="T123456"

# Google Drive Server
GOOGLE_CLIENT_ID="xxx.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="xxx"
GOOGLE_REFRESH_TOKEN="xxx"

🏗️ Protocol Architecture

Three-Layer Protocol System (Chapter 10 Design)

Agent Communication Protocol Architecture
├── Application Layer
│   ├── MCPTool - MCP protocol tool wrapper
│   ├── A2ATool - A2A protocol tool wrapper
│   └── ANPTool - ANP protocol tool wrapper
│
├── Protocol Layer
│   ├── MCP (Model Context Protocol)
│   │   ├── MCPClient - Multi-transport client
│   │   │   ├── Memory Transport (testing)
│   │   │   ├── Stdio Transport (local development)
│   │   │   ├── Command Transport (flexible configuration)
│   │   │   ├── HTTP Transport (production)
│   │   │   └── SSE Transport (real-time)
│   │   └── MCPServer - FastMCP-based server wrapper
│   │
│   ├── A2A (Agent-to-Agent Protocol)
│   │   ├── A2AServer - Agent server implementation
│   │   ├── A2AClient - Agent client for communication
│   │   ├── AgentNetwork - Multi-agent network management
│   │   └── AgentRegistry - Agent discovery and registration
│   │
│   └── ANP (Agent Network Protocol)
│       ├── ANPDiscovery - Service discovery mechanism
│       ├── ANPNetwork - Network topology management
│       └── ServiceInfo - Service metadata and health check
│
└── Transport Layer
    ├── Stdio - Standard input/output (local processes)
    ├── HTTP - RESTful API (remote services)
    ├── SSE - Server-Sent Events (real-time streaming)
    └── Memory - In-memory (testing and prototyping)

🔧 MCP (Model Context Protocol)

Overview

MCP enables agents to access external tools, resources, and prompts through a standardized protocol. HelloAgents provides a complete MCP implementation with support for multiple transport modes.

Key Features:

• 5 Transport Modes: Memory, Stdio, Command, HTTP, SSE
• Auto Environment Detection: Automatically detects required environment variables
• Built-in Demo Server: No configuration needed for quick start
• Official Server Support: Compatible with all official MCP servers
• Tool Auto-expansion: Automatically expands server tools as individual agent tools

Transport Modes Comparison

Quick Start

from hello_agents import SimpleAgent, HelloAgentsLLM
from hello_agents.tools import MCPTool

# Create agent
agent = SimpleAgent(name="Assistant", llm=HelloAgentsLLM())

# Method 1: Use built-in demo server (no configuration needed)
mcp_tool = MCPTool()  # Auto-creates demo server with math tools
agent.add_tool(mcp_tool)

# Method 2: Connect to external MCP server
fs_tool = MCPTool(
    name="filesystem",
    description="Access local file system",
    server_command=["npx", "-y", "@modelcontextprotocol/server-filesystem", "."]
)
agent.add_tool(fs_tool)

# Method 3: Use custom FastMCP server
from fastmcp import FastMCP

server = FastMCP("WeatherServer")

@server.tool()
def get_weather(city: str) -> str:
    """Get weather for a city"""
    return f"Weather in {city}: Sunny, 25°C"

weather_tool = MCPTool(name="weather", server=server)
agent.add_tool(weather_tool)

# Use the agent
response = agent.run("What's the weather in Beijing?")

Advanced Features

Environment Variable Management:

# Priority 1: Direct env parameter (highest)
github_tool = MCPTool(
    name="github",
    server_command=["npx", "-y", "@modelcontextprotocol/server-github"],
    env={"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"}
)

# Priority 2: Load from .env file
github_tool = MCPTool(
    name="github",
    server_command=["npx", "-y", "@modelcontextprotocol/server-github"],
    env_keys=["GITHUB_PERSONAL_ACCESS_TOKEN"]
)

# Priority 3: Auto-detection (based on server name)
github_tool = MCPTool(
    name="github",
    server_command=["npx", "-y", "@modelcontextprotocol/server-github"]
    # Automatically detects GITHUB_PERSONAL_ACCESS_TOKEN
)

Tool Auto-expansion:

# Auto-expand: Each server tool becomes an independent agent tool
mcp_tool = MCPTool(auto_expand=True)  # Default
# Agent can directly call: add, subtract, multiply, divide, etc.

# Manual mode: Use MCP tool as a single unified tool
mcp_tool = MCPTool(auto_expand=False)
# Agent calls: mcp(action="call_tool", tool_name="add", arguments={...})

Supported Official MCP Servers

🤝 A2A (Agent-to-Agent Protocol)

Overview

A2A enables direct communication and collaboration between agents. HelloAgents integrates the official A2A SDK, providing a clean wrapper for agent-to-agent interactions.

Key Features:

• Official SDK Integration: Based on a2a-sdk library
• Skill Sharing: Agents can share and invoke each other's skills
• Task Delegation: Agents can delegate tasks to specialized agents
• Network Management: Built-in agent registry and discovery

Quick Start

from hello_agents.protocols import A2AServer, AgentNetwork

# Create agent network
network = AgentNetwork()

# Create specialized agents
writer = A2AServer(
    name="Writer Agent",
    description="Content writing specialist",
    version="1.0.0",
    capabilities={"writing": True, "editing": True}
)

@writer.skill("write_article")
def write_article(topic: str) -> str:
    """Write an article on a topic"""
    return f"Article about {topic}..."

reviewer = A2AServer(
    name="Reviewer Agent",
    description="Content review specialist",
    version="1.0.0",
    capabilities={"review": True, "feedback": True}
)

@reviewer.skill("review_content")
def review_content(content: str) -> str:
    """Review and provide feedback"""
    return f"Review: {content} looks good!"

# Register agents
network.register(writer)
network.register(reviewer)

# Agent collaboration
article = writer.call_skill("write_article", {"topic": "AI"})
feedback = reviewer.call_skill("review_content", {"content": article})

Use Cases

• Content Creation Teams: Writer, Editor, Reviewer agents
• Customer Service: Routing, Support, Escalation agents
• Code Review Workflows: Developer, Reviewer, Tester agents
• Educational Systems: Teacher, Tutor, Evaluator agents

🌐 ANP (Agent Network Protocol)

Overview

ANP provides service discovery, network management, and load balancing for large-scale agent systems. This is a conceptual implementation designed for educational purposes.

Key Features:

• Service Discovery: Automatic agent discovery and registration
• Network Topology: Visualize and manage agent networks
• Load Balancing: Distri...

HelloAgents V0.2.0 Release Notes

📅 Last Updated: 2025-10-01
📦 Package: pip install hello-agents[mem-rag]
🔗 GitHub: https://github.com/jjyaoao/HelloAgents

🎯 Overview

The HelloAgents memory system provides complete memory and RAG (Retrieval-Augmented Generation) capabilities to enhance Agent abilities through a tooling approach. The system adopts a layered architecture design, implementing four memory types and hybrid storage backends according to Chapter 8 architecture.

✨ Core Features

• 🧠 Four Memory Types: Working Memory, Episodic Memory, Semantic Memory, Perceptual Memory
• 💾 Hybrid Storage Architecture: SQLite (document store) + Qdrant (vector retrieval) + Neo4j (knowledge graph)
• 🔍 Intelligent Retrieval: Vector retrieval + Graph retrieval + Fusion ranking
• 🌐 Multilingual Support: Default paraphrase-multilingual-MiniLM-L12-v2 multilingual embedding model
• 🎨 Multimodal Support: Text, Image, Audio (Perceptual Memory)
• 🔧 Tool Interface: MemoryTool and RAGTool fully compliant with HelloAgents framework

🔧 Installation & Dependencies

Installation

# Basic memory system
pip install hello-agents[memory]

# With RAG capabilities
pip install hello-agents[rag]

# Full installation (memory + RAG + multimodal)
pip install hello-agents[mem-rag]

Dependencies

Environment Configuration

Optional Environment Variables:

# Qdrant Configuration
QDRANT_URL="https://<your-qdrant-endpoint>:6333"
QDRANT_API_KEY="<your-api-key>"
QDRANT_COLLECTION="hello_agents_vectors"
QDRANT_DISTANCE="cosine"

# Neo4j Configuration
NEO4J_URI="bolt://localhost:7687"
NEO4J_USER="neo4j"
NEO4J_PASSWORD="<your-password>"

# Embedding Model Configuration
EMBED_MODEL_TYPE="local"  # local/dashscope/tfidf
EMBED_MODEL_NAME="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"

🏗️ System Architecture

Layered Architecture (Chapter 8 Design)

Memory System Architecture
├── Tools Layer
│   ├── MemoryTool - Unified memory interface
│   └── RAGTool - Retrieval-Augmented Generation tool
│
├── Memory Core Layer
│   └── MemoryManager - Memory lifecycle management
│       ├── Memory lifecycle management
│       ├── Priority evaluation
│       ├── Forgetting and cleanup
│       └── Multi-type coordination
│
├── Memory Types Layer
│   ├── WorkingMemory - Short-term memory
│   │   └── Pure in-memory + TTL auto-expiration
│   ├── EpisodicMemory - Event memory
│   │   └── SQLite (authoritative) + Qdrant (vector index)
│   ├── SemanticMemory - Knowledge memory
│   │   └── Qdrant (vectors) + Neo4j (knowledge graph)
│   └── PerceptualMemory - Sensory memory
│       └── SQLite (metadata) + Qdrant (multimodal vectors)
│
├── Storage Layer
│   ├── QdrantVectorStore - Vector storage
│   │   ├── Multilingual embeddings (default 384-dim)
│   │   ├── Modality-based collections (text/image/audio)
│   │   └── Efficient vector retrieval
│   ├── Neo4jGraphStore - Graph storage
│   │   ├── spaCy entity recognition
│   │   ├── Co-occurrence relationship graph
│   │   └── Graph retrieval and reasoning
│   └── SQLiteDocumentStore - Document storage
│       ├── Structured metadata
│       ├── Time/session/importance filtering
│       └── Authoritative data source
│
└── RAG Layer
    ├── DocumentProcessor - Document processing
    │   ├── Multi-format support (PDF/Word/Excel/PPT)
    │   ├── Intelligent chunking
    │   └── Language tagging and deduplication
    ├── EmbeddingModel - Embedding models
    │   ├── LocalTransformerEmbedding (default)
    │   ├── TFIDFEmbedding (fallback)
    │   └── Intelligent degradation
    └── RAGPipeline - RAG pipeline
        ├── Vector retrieval
        ├── Graph-enhanced retrieval
        ├── Fusion ranking
        └── Snippet merging

🧠 Memory Types

WorkingMemory - Short-term Memory

Short-term memory for storing current session context information.

Architecture Features:

• Storage: Pure in-memory (Python dict), no external database dependency
• Capacity Limit: Default 10 items, configurable (working_memory_capacity)
• Token Limit: Default 2000 tokens, configurable (working_memory_tokens)
• TTL Mechanism: Default 120 minutes auto-expiration, configurable (working_memory_ttl_minutes)
• Priority Management: importance × time decay, auto-eviction of low-priority memories
• Session-level: Auto-cleanup on session end

Implementation Details:

• Uses collections.deque for FIFO queue
• Auto-cleanup of expired memories on each access (TTL check)
• Priority-based eviction when capacity is full (importance × recency_score)
• No vector retrieval dependency, direct time and importance-based sorting

Use Cases:

• Conversation context tracking
• Temporary task state management
• Recent interaction history
• Session-specific information

EpisodicMemory - Event Memory

Stores specific interaction events and experiences using a "authoritative store + vector index" dual-storage architecture.

Architecture Features:

• Authoritative Storage: SQLite (structured metadata, time series, session management)
• Vector Index: Qdrant (semantic retrieval, default 384-dim multilingual embeddings)
• Retrieval Strategy: Structured filtering + Vector retrieval + Fusion ranking
• Ranking Formula: vector×0.6 + recency×0.2 + importance×0.2
• Time Series: Support for time range queries and session filtering
• Pattern Recognition: Behavior pattern discovery based on time series

Implementation Details:

• SQLite schema: id, content, user_id, timestamp, importance, session_id, metadata
• Qdrant collection: <base>_episodic, payload contains memory_id, user_id, session_id
• Write flow: SQLite first (authoritative) → Qdrant second (index)
• Retrieval flow: SQLite filtering → Qdrant vector recall → Fusion ranking
• Deletion strategy: Filter by payload memory_id (avoid UUID mismatch)

Use Cases:

• User interaction history
• Event logging and replay
• Session-based memory retrieval
• Temporal pattern analysis

SemanticMemory - Knowledge Memory

Stores abstract knowledge and concept relationships using a "vector + graph" hybrid retrieval architecture.

Architecture Features:

• Vector Retrieval: Qdrant vector database (multilingual embeddings, default 384-dim)
• Graph Retrieval: Neo4j knowledge graph (spaCy entity recognition, co-occurrence relationships)
• Fusion Ranking: graph×0.6 + vector×0.4 + importance×0.05
• Multilingual Support: Default paraphrase-multilingual-MiniLM-L12-v2, auto-fallback
• Entity Recognition: spaCy NER (PERSON/ORG/GPE/PRODUCT, etc.)
• Relationship Modeling: Co-occurrence relationships only, avoiding over-inference

Implementation Details:

• Qdrant collection: <base>_semantic, payload contains memory_id, user_id, concepts
• Neo4j graph: Nodes (entities + concepts), Edges (co-occurrence + weights)
• Write flow:
  1. spaCy entity extraction → Neo4j graph building (entity nodes + co-occurrence edges)
  2. Generate embeddings → Qdrant indexing
• Retrieval flow:
  1. Qdrant vector recall (top-k candidates)
  2. Neo4j graph expansion (related entities + concepts)
  3. Fusion ranking (vector similarity + graph signal + importance)
• Graph signal: PageRank centrality + co-occurrence frequency

Use Cases:

• Knowledge base management
• Concept relationship discovery
• Entity-centric retrieval
• Semantic reasoning and inference

PerceptualMemory - Sensory Memory

Designed for "long-term multimodal" data (text/image/audio).

Architecture Features:

• Storage: SQLite (authoritative) + Qdrant (vector index)
• Modality-based Collections: Avoid vector dimension conflicts
  • <base>_perceptual_text (text)
  • <base>_perceptual_image (image)
  • <base>_perceptual_audio (audio)
• Encoding Strategy (lazy loading):
  • Text: sentence-transformers (default paraphrase-multilingual-MiniLM-L12-v2)
  • Image (optional): CLIP (e.g., openai/clip-vit-base-patch32); fallback to deterministic hash vectors
  • Audio (optional): CLAP (e.g., laion/clap-htsat-unfused, requires librosa); fallback to deterministic hash vectors
• Same-modality Retrieval: Vector retrieval + time/importance fusion (0.6*vector + 0.2*recency + 0.2*importance)
• Cross-modality Retrieval: Requires CLIP/CLAP; hash fallback only supports "same-source file" matching

Implementation Details:

• SQLite schema: id, content, user_id, timestamp, importance, modality, raw_data, metadata
• Qdrant collections: Separate collections per modality to avoid dimension conflicts
• Write flow: SQLite metadata storage → Modality-based encoding → Qdrant indexing
• Retrieval flow: Determine target modality → Qdrant vector recall → Fusion ranking
• Cross-modality: Requires CLIP/CLAP support, otherwise only same-source file matching

Use Cases:

• Image memory and retrieval
• Audio recording and search
• Multimodal content management
• Cross-modal semantic search

🔍 RAG System

RAGTool - Retrieval-Augmented Generation Too...

HelloAgents V0.1.1 Release Notes

🎉 Release Date: 2025-9-22
📦 Package: pip install hello-agents==0.1.1
🔗 GitHub: https://github.com/jjyaoao/HelloAgents

🚀 What's New in v0.1.1

HelloAgents v0.1.1 is a major update that introduces advanced tool system capabilities, enhanced search functionality, and comprehensive framework improvements. This release represents a significant step forward in building production-ready AI agent applications.

✨ Major Features

🔧 Advanced Tool System

• Tool Chain Management: New ToolChain and ToolChainManager classes for sequential tool execution
• Async Tool Execution: AsyncToolExecutor for parallel and batch tool processing
• Enhanced Tool Registry: Improved function registration with better error handling
• Tool Workflow Support: Variable passing between tool execution steps

🔍 Enhanced Search Capabilities

• Multi-Source Search Integration: Support for Tavily and SerpAPI with intelligent fallback
• Smart Backend Selection: Automatic selection of best available search source
• User-Friendly Error Messages: Clear API configuration guidance instead of mock results
• Professional Error Handling: Detailed setup instructions for missing dependencies

🏗️ Framework Architecture Improvements

• Five-Layer Architecture: Clean separation of concerns across all framework layers
• Unified LLM Interface: Enhanced HelloAgentsLLM with multi-provider support
• Standardized Message System: Consistent message handling across all agent types
• Comprehensive Exception System: Professional error handling and user feedback

🎯 Agent Implementations

Four Complete Agent Paradigms

• SimpleAgent: Basic conversational agent with tool integration
• ReActAgent: Reasoning and Acting agent with Think-Act-Observe cycles
• ReflectionAgent: Self-reflection and iterative improvement capabilities
• PlanAndSolveAgent: Task decomposition and step-by-step execution

🛠️ Developer Experience

Enhanced Development Tools

• Complete Test Suite: Comprehensive testing in examples/chapter07_basic_setup.py
• Interactive Demos: Real-time agent testing and comparison
• Professional Documentation: Detailed API docs and usage examples
• Type Safety: Full type hints and validation throughout the codebase

Package Management

• Optional Dependencies: pip install hello-agents[search] for search capabilities
• Clean Imports: All major components available from main package
• Version Compatibility: Stable API with backward compatibility guarantees

🔄 Breaking Changes

Tool System Updates

• Removed Mock Search: Replaced mock search functionality with user-friendly API configuration guidance
• Updated Import Paths: Some internal imports have been reorganized for better structure
• Enhanced Error Messages: More specific and actionable error information

API Improvements

• Standardized Tool Registration: Consistent function registration across all tool types
• Unified Exception Handling: All exceptions now inherit from HelloAgentsException
• Enhanced Configuration: Better environment variable handling and validation

🐛 Bug Fixes

• Fixed Chinese font rendering issues in architecture diagrams
• Resolved tool execution error handling in edge cases
• Improved memory management in async tool execution
• Fixed import issues when using pip-installed packages
• Enhanced error messages for missing API keys and dependencies

📈 Performance Improvements

• Async Tool Execution: Up to 4x faster parallel tool processing
• Optimized Tool Registry: Improved tool lookup and execution performance
• Memory Efficiency: Better resource management in long-running applications
• Connection Pooling: Efficient handling of external API connections

📚 Documentation & Examples

New Documentation

• Complete API Reference: Detailed documentation for all classes and methods
• Architecture Diagrams: Visual representation of framework structure and execution flow
• Best Practices Guide: Professional development guidelines and patterns
• Migration Guide: Step-by-step upgrade instructions from previous versions

Enhanced Examples

• Interactive Demo: chapter07_basic_setup.py with full framework demonstration
• Tool Development Guide: Step-by-step custom tool creation examples
• Agent Comparison: Side-by-side comparison of different agent paradigms
• Production Deployment: Real-world usage patterns and configurations

🔧 Installation & Upgrade

New Installation

# Basic installation
pip install hello-agents==0.1.1

# With search capabilities
pip install hello-agents[search]==0.1.1

# Full installation with all features
pip install hello-agents[all]==0.1.1

Upgrade from v0.1.0

pip install --upgrade hello-agents==0.1.1

Dependencies

• Core: openai>=1.0.0, pydantic>=2.0.0, requests>=2.25.0
• Search: tavily-python>=0.3.0, serpapi>=0.1.0 (optional)
• Development: pytest>=7.0.0, black>=22.0.0 (optional)

🎯 What's Next

Upcoming in v0.2.0

• Memory & RAG System: Advanced context management and retrieval capabilities
• Multi-Agent Orchestration: Agent-to-agent communication and coordination
• Enhanced Context Engineering: Advanced prompt management and optimization
• Production Monitoring: Logging, metrics, and observability features

Community & Contributions

• GitHub Discussions: Join our community for questions and feature requests
• Contributing Guide: Help us improve HelloAgents with your contributions
• Issue Tracking: Report bugs and request features on GitHub
• Documentation: Help us improve documentation and examples

🙏 Acknowledgments

Special thanks to all contributors, testers, and community members who made this release possible. Your feedback and contributions have been invaluable in shaping HelloAgents into a robust and user-friendly framework.

Key Contributors

• Framework Architecture & Core Implementation
• Tool System Design & Advanced Features
• Documentation & Examples
• Testing & Quality Assurance

📞 Support & Community

• GitHub Issues: https://github.com/jjyaoao/HelloAgents/issues
• Documentation: https://github.com/jjyaoao/HelloAgents/blob/main/README.md
• Examples: https://github.com/jjyaoao/HelloAgents/tree/main/examples
• Email: jjyaoao@126.com

Happy Building with HelloAgents! 🤖✨