21 Feb 05:58

jjyaoao

9ff239a

V1.0.0 Latest

Latest

HelloAgents V1.0.0 Release Notes

📅 发布日期: 2026-02-21
📦 安装: pip install hello-agents>=1.0.0
🔗 GitHub: https://github.com/jjyaoao/HelloAgents
📚 文档: https://github.com/jjyaoao/HelloAgents/tree/main/docs

🎯 概述

HelloAgents V1.0.0 是一个里程碑版本，标志着框架从教学原型升级为生产级多智能体框架。本版本集成了 16 项核心能力，涵盖工具响应协议、上下文工程、可观测性、会话持久化、子代理机制、异步生命周期、流式输出等完整的工程化支持，为构建复杂智能体应用提供坚实基础。(感谢项目YYHDBL/MyCodeAgent给予的部分实现灵感支持~)

✨ 核心亮点

🏗️ 生产级架构: Function Calling 统一架构，解析成功率 99%+
🔧 16 项核心能力: 从工具协议到异步生命周期的完整工程化支持
🚀 性能优化: Token 成本降低 85%，上下文压缩智能化
🔍 可观测性: 双格式审计日志（JSONL + HTML）
🔄 会话持久化: 断点续跑，异常自动保存
🌐 多 LLM 支持: OpenAI/Anthropic/Gemini 三种适配器
📊 流式输出: SSE 实时响应，支持前端集成
⚡ 异步架构: 工具并行执行，生命周期钩子

🔧 安装与升级

新安装

# 基础安装
pip install hello-agents>=1.0.0

# 完整安装（包含所有可选依赖）
pip install hello-agents[all]

从旧版本升级

# 升级到最新版本
pip install --upgrade hello-agents

# 指定版本
pip install hello-agents==1.0.0

验证安装

import hello_agents
print(hello_agents.__version__)  # 应输出: 1.0.0

🆕 核心特性

阶段 1：基础设施

1. 工具响应协议（ToolResponse）

问题: 旧版本工具返回纯字符串，状态不明确，错误处理依赖正则解析

解决方案: 统一 ToolResponse 协议

from hello_agents.tools import ToolResponse, ToolStatus, ToolErrorCode

# 成功响应
return ToolResponse.success(
    text="计算结果: 5",
    data={"result": 5, "expression": "2+3"},
    stats={"time_ms": 10}
)

# 部分成功（截断、回退）
return ToolResponse.partial(
    text="结果已截断...",
    error_code=ToolErrorCode.TRUNCATED,
    data={"full_path": "tool-output/xxx.json"}
)

# 错误响应
return ToolResponse.error(
    text="文件不存在",
    error_code=ToolErrorCode.NOT_FOUND
)

收益:

✅ 三种状态：SUCCESS / PARTIAL / ERROR
✅ 15 种标准错误码
✅ 结构化数据传递
✅ 自动时间统计

2. 上下文工程（Context Engineering）

问题: 长对话无限增长导致爆窗、Token 成本爆炸、缓存失效

解决方案: HistoryManager + TokenCounter + ObservationTruncator

from hello_agents import ReActAgent, HelloAgentsLLM, Config

# 配置上下文工程
config = Config(
    context_window=128000,           # 上下文窗口
    compression_threshold=0.8,       # 80% 时触发压缩
    min_retain_rounds=10,            # 保留最近 10 轮
    enable_smart_compression=False,  # 简单摘要（默认）
    tool_output_max_lines=2000,      # 工具输出截断
    tool_output_max_bytes=51200      # 50KB
)

agent = ReActAgent("assistant", HelloAgentsLLM(), config=config)

收益:

✅ 自动历史压缩（summary + 最近 N 轮）
✅ 缓存友好设计（只追加，不编辑）
✅ Token 计数优化（O(n) → O(1)）
✅ 工具输出统一截断
✅ 智能摘要生成（可选）

阶段 2：核心能力

3. 可观测性（TraceLogger）

问题: 无法追踪 Agent 执行轨迹，调试困难

解决方案: 双格式审计日志（JSONL + HTML）

from hello_agents import ReActAgent, HelloAgentsLLM, Config

# 启用 TraceLogger（默认启用）
config = Config(
    trace_enabled=True,
    trace_output_dir="memory/traces"
)

agent = ReActAgent("assistant", HelloAgentsLLM(), config=config)
agent.run("分析项目结构")

# 查看日志
# - memory/traces/trace-20250221-103045.jsonl（机器可读）
# - memory/traces/trace-20250221-103045.html（人类可读）

收益:

✅ 实时流式追加
✅ 自动脱敏（API Key、路径）
✅ 内置统计（Token、工具调用、错误）
✅ 可视化界面（HTML 交互式面板）

4. 熔断器（CircuitBreaker）

问题: 工具连续失败导致资源浪费

解决方案: 自动熔断机制，连续失败 3 次自动禁用工具，5 分钟后恢复

收益:

✅ Token 成本节省 97%（3 次失败 vs 无限重试）
✅ 自动监控工具执行
✅ 定时自动恢复
✅ 零配置开箱即用

📖 详细文档: circuit-breaker-guide.md

5. 会话持久化（SessionStore）

问题: 会话仅存在内存，崩溃即丢失

解决方案: 完整的会话保存/恢复机制

收益:

✅ 断点续跑（长时间任务）
✅ 异常自动保存（Ctrl+C / Exception）
✅ 环境一致性检查（配置、工具 Schema）
✅ Read 工具缓存集成（支持乐观锁）

📖 详细文档: session-persistence-guide.md

阶段 3：增强能力

6. 子代理机制（SubAgent）

问题: 复杂任务难以分解，上下文混乱

解决方案: 主子 Agent 协作，上下文隔离

核心特性:

✅ 所有 Agent 类型都可作为子代理（react/reflection/plan/simple）
✅ 工具过滤（ReadOnly/FullAccess/Custom）
✅ 轻量模型路由（子任务用 DeepSeek，节省 70% 成本）
✅ TaskTool 零配置集成

📖 详细文档: subagent-guide.md

7. Skills 知识外化

问题: 领域知识硬编码在系统提示词，Token 成本高

解决方案: 渐进式披露机制

核心特性:

✅ 启动时仅加载元数据（~100 tokens/skill）
✅ 按需加载完整技能（~2000+ tokens）
✅ 人类可编辑（Markdown 格式）
✅ 零配置（检测 skills/ 目录自动激活）

收益: Token 成本降低 85%（40K → 6K）

📖 详细文档: skills-usage-guide.md

8. 乐观锁机制（Optimistic Locking）

问题: 多 Agent 协作时文件冲突

解决方案: Read 时缓存元数据，Write/Edit 时检测冲突

核心特性:

✅ 4 个文件工具（Read/Write/Edit/MultiEdit）
✅ 自动冲突检测（基于 mtime）
✅ 自动备份机制（.backups/）
✅ 原子写入保证

📖 详细文档: file_tools.md

9. TodoWrite 进度管理

问题: 任务状态通过对话历史跟踪，易遗漏

解决方案: 结构化任务列表管理

核心特性:

✅ 单线程强制（最多 1 个 in_progress）
✅ 自动 Recap 生成（[2/5] 进行中: xxx）
✅ 持久化支持断点恢复
✅ 零配置集成

📖 详细文档: todowrite-usage-guide.md

阶段 4：辅助功能

10. DevLog 开发日志

问题: Agent 决策过程不透明

解决方案: 结构化开发日志工具

核心特性:

✅ 7 种类别（decision/progress/issue/solution/refactor/test/performance）
✅ 持久化到 memory/devlogs/
✅ 支持过滤查询
✅ Agent 可用工具

📖 详细文档: devlog-guide.md

11. 异步生命周期

问题: 同步执行效率低

解决方案: 完整的异步支持

核心特性:

✅ arun() / arun_stream() 异步方法
✅ 工具并行执行（用户工具并行，内置工具串行）
✅ 生命周期钩子（on_start/on_step/on_tool_call/on_finish/on_error）
✅ 向后兼容（现有 run() 方法不变）

📖 详细文档: async-agent-guide.md

阶段 5：核心架构重构

12. 流式输出与 SSE

问题: 长时间等待，用户体验差

解决方案: 真正的异步流式输出

核心特性:

✅ 使用 AsyncOpenAI 原生客户端
✅ SSE 标准协议（兼容浏览器 EventSource）
✅ 8 种事件类型（AGENT_START/STEP_START/TOOL_CALL/LLM_CHUNK 等）
✅ FastAPI 集成示例

性能提升: 首字节时间从 15 秒降低到 1.3 秒（11.7 倍）

📖 详细文档: streaming-sse-guide.md

13-14. Function Calling 统一架构

问题: ReActAgent 使用正则解析，成功率 85-90%

解决方案: 所有 Agent 类型统一使用 Function Calling

核心成果:

✅ LLM 基类重构（invoke_with_tools() 统一接口）
✅ 3 种适配器（OpenAI/Anthropic/Gemini）
✅ 4 个 Agent 完整重构（ReAct/Simple/Reflection/Plan）
✅ 解析成功率提升到 99%+

📖 详细文档: function-calling-architecture.md

15. 日志系统（四种范式）

问题: 日志系统混乱，难以调试

解决方案: 分层日志设计

四种范式:

TraceLogger - 生产审计轨迹（JSONL + HTML）
AgentLogger - 开发日志（结构化，轮转）
DevLogTool - 开发决策记录（Agent 可用）
标准 logging - 框架内部日志

📖 详细文档: logging-system-guide.md

16. 自定义工具扩展

问题: 用户不知道如何创建自定义工具

解决方案: 完整的扩展机制 + 文档 + 模板

三种实现方式:

函数式工具（最简单）- registry.register_function(my_func)
标准工具类（推荐）- 继承 Tool 基类
可展开工具（高级）- @tool_action 装饰器

📖 详细文档: custom_tools_guide.md

主要变更

工具返回值: str → ToolResponse 对象
Agent 架构: 正则解析 → Function Calling

向后兼容

✅ 函数工具自动包装为新协议
✅ 现有 run() 方法完全不变
✅ 配置项可选（默认启用，可禁用）

📚 迁移指南

从 v0.x 迁移到 v1.0.0

1. 更新工具实现

# 旧版本
def my_tool(input: str) -> str:
    return "结果"

# 新版本
from hello_agents.tools import Tool, ToolResponse

class MyTool(Tool):
    def run(self, parameters):
        return ToolResponse.success(text="结果")

2. 更新 Agent 创建

# 旧版本和新版本完全相同
agent = ReActAgent("assistant", llm, tool_registry=registry)

3. 启用新特性

from hello_agents import Config

config = Config(
    trace_enabled=True,           # 可观测性
    session_enabled=True,         # 会话持久化
    subagent_enabled=True,        # 子代理
    skills_enabled=True,          # Skills
    todowrite_enabled=True        # TodoWrite
)

🎉 致谢与展望

致谢

感谢所有贡献者和学习者的支持，V1.0.0 的完成离不开社区的反馈和建议。

Assets 2

13 Feb 05:48

jjyaoao

V0.2.9

6749914

V0.2.9

🎓 HelloAgents V0.2.9 - 学习版定稿公告

📅 发布日期: 2026-02-13
📦 版本: v0.2.9 (Learning Edition - Stable)
🔗 GitHub: https://github.com/jjyaoao/HelloAgents
📚 教程: https://github.com/datawhalechina/Hello-Agents

🎯 核心公告

HelloAgents V0.2.9 正式定稿为「学习版」，从此版本开始：

✅ 接口冻结：核心 API 保持稳定，不再引入破坏性变更
✅ 教程基准：所有教程、文档、示例代码均基于此版本
✅ 长期维护：仅接受 bug 修复和安全更新，不添加新特性
✅ 初学者友好：推荐所有初学者和教程读者使用此版本

📖 为什么需要学习版？

在过去的开发中，我们收到了很多反馈：

"教程里的代码跑不通了，API 变了..."
"刚学会一个功能，更新后又不一样了..."
"能不能有个稳定版本，让我安心学完整个教程？"

我们听到了你们的声音！

V0.2.9 学习版的目标是：

🎓 教学优先：为 Datawhale《Hello-Agents》教程提供稳定基础
📚 文档完整：所有示例代码保证可运行
🔒 接口稳定：学习过程中不会遇到 API 变更
🌱 循序渐进：从简单到复杂，逐步掌握 Agent 开发

🚀 V0.2.9 核心特性

1. 核心框架

from hello_agents import SimpleAgent, HelloAgentsLLM

# 最简单的 Agent
llm = HelloAgentsLLM(model="gpt-4")
agent = SimpleAgent("助手", llm)
response = agent.run("你好")

2. 工具系统

from hello_agents.tools import SearchTool, ToolRegistry

# 工具注册与使用
search = SearchTool(backend="tavily")
registry = ToolRegistry()
registry.register_tool(search)

agent = SimpleAgent("搜索助手", llm, tool_registry=registry)

3. 记忆系统

from hello_agents.memory import VectorMemory, GraphMemory

# 向量记忆
vector_mem = VectorMemory()
vector_mem.add("重要信息")

# 图记忆
graph_mem = GraphMemory()
graph_mem.add_entity("Alice", "Person")

4. RAG 系统

from hello_agents.tools import RAGTool

# RAG 工具
rag = RAGTool(docs_path="./docs")
rag.index_documents()
results = rag.search("如何使用 Agent?")

5. 协议支持

from hello_agents.protocols import MCPServer

# MCP 协议
server = MCPServer("my-server")
server.add_tool(search)
server.run()

📦 安装指南

基础安装

pip install hello-agents==0.2.9

完整安装

# 所有功能（推荐学习使用）
pip install hello-agents[all]==0.2.9

# 或按需安装
pip install hello-agents[search]==0.2.9        # 搜索功能
pip install hello-agents[memory]==0.2.9        # 记忆系统
pip install hello-agents[rag]==0.2.9           # RAG 系统
pip install hello-agents[protocols]==0.2.9     # MCP/A2A 协议
pip install hello-agents[evaluation]==0.2.9    # 评估工具

验证安装

import hello_agents
print(hello_agents.__version__)  # 应输出: 0.2.9

🔮 下一步：Dev 开发版

在保持学习版稳定的同时，我们将启动 Dev 开发版 分支，用于探索和集成新特性：

Dev 版将保持对学习版的接口兼容：

✅ 学习直接在 Dev 版运行
✅ 新特性通过可选参数添加
✅ 不破坏现有 API 设计
✅ 提供平滑迁移路径

📚 学习资源

官方教程

贡献指南

学习版虽然冻结新特性，但我们欢迎：

✅ Bug 修复
✅ 文档改进
✅ 示例代码优化
✅ 测试用例补充

🙏 致谢

感谢所有为 HelloAgents 做出贡献的开发者和学习者！

特别感谢：

Datawhale 社区：提供教学平台和反馈
早期用户：帮助我们发现和修复问题
贡献者：提交代码和文档改进
所有学习者：你们的反馈推动了学习版的诞生

Assets 2

26 Oct 07:34

jjyaoao

V0.2.8

707949e

V0.2.8

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):

Provider	Type	Auto-detect	Custom Config
ModelScope	Cloud	✅	✅
OpenAI	Cloud	✅	✅
DeepSeek	Cloud	✅	✅
通义千问	Cloud	✅	✅
Kimi	Cloud	✅	✅
智谱GLM	Cloud	✅	✅
Ollama	Local	✅	✅
vLLM	Local	✅	✅
Custom	Any	❌	✅

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:

Tool Call Monitoring: Track search and note-taking in real-time
Custom Provider: Support local and cloud LLMs seamlessly
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...

Assets 2

23 Oct 05:15

jjyaoao

V0.2.7

3b694d7

V0.2.7

update dependency, Fixed numpy dependency error caused by bfcl.

add builder in chapter9.
fix import error in chapter9.

Assets 2

19 Oct 13:28

jjyaoao

V0.2.6

9dd9bd5

V0.2.6

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

for chapter9

Assets 2

18 Oct 05:15

jjyaoao

V0.2.5

65bebf2

V0.2.5

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

Component	Packages	Description
TRL	`trl>=0.12.0`	Transformer Reinforcement Learning
Transformers	`transformers>=4.40.0`	HuggingFace Transformers
PEFT	`peft>=0.10.0`	Parameter-Efficient Fine-Tuning
Datasets	`datasets>=2.18.0`	HuggingFace Datasets
Accelerate	`accelerate>=0.28.0`	Distributed training support
DeepSpeed (optional)	`deepspeed>=0.14.0`	Advanced distributed training
Wandb (optional)	`wandb>=0.16.0`	Experiment tracking
TensorBoard	`tensorboard>=2.15.0`	Training visualization
Core Framework	`hello-agents>=0.2.5`	HelloAgents framework

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

Reward Type	Description	Use Case
accuracy	Exact match with ground truth	Math problems, QA
length_penalty	Penalize overly long responses	Concise generation
step	Reward based on reasoning steps	Multi-step reasoning

# 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

Table: Distributed Training Methods Comparison

Method	Use Case	Memory Savings	Speed	Complexity
DDP	Single machine, 2-8 GPUs	None	Fastest	Low
ZeRO-2	Medium models (1B-7B)	~30%	Fast	Medium
ZeRO-3	Large models (>7B)	~50%	Moderate	High
Multi-Node	Very large models	~50%+	Scalable	High

Quick St...

Assets 2

13 Oct 10:18

jjyaoao

V0.2.4

de67ddb

V0.2.4

Fix some bug for chapter13. The function is unchanged.

Assets 2

11 Oct 09:12

jjyaoao

V0.2.3

9a1af1b

V0.2.3

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

Component	Packages	Description
BFCL Evaluation	`bfcl-eval` (optional)	Official BFCL evaluation tool
GAIA Evaluation	`datasets`	HuggingFace datasets for GAIA benchmark
Data Generation	`tqdm`, `numpy`	Progress tracking and numerical operations
Core Framework	`hello-agents>=0.2.3`	HelloAgents framework

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

Category	Samples	Description	Difficulty
simple_python	400	Single Python function call	⭐
simple_java	400	Single Java function call	⭐
simple_javascript	400	Single JavaScript function call	⭐
multiple	240	Multiple function calls in sequence	⭐⭐
parallel	280	Parallel function calls	⭐⭐⭐
parallel_multiple	200	Parallel multiple function calls	⭐⭐⭐⭐
irrelevance	200	Detect when no function should be called	⭐⭐⭐

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

Level	Samples	Reasoning Steps	Success Rate (GPT-4)	Difficulty
Level 1	165	0 steps	~80%	⭐
Level 2	184	1-5 steps	~50%	⭐⭐⭐
Level 3	117	5+ steps	~20%	⭐⭐⭐⭐⭐

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

Method	Type	Metrics	Use Case
LLM Judge	Absolute	4 dimensions × 5-point scale	Quality assessment
Win Rate	Relative	Win/Loss/Tie percentage	Comparison with reference
Human Verification	Manual	Pass/Fail + feedback	Final quality check

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...

Assets 2

11 Oct 09:04

jjyaoao

V0.2.2

a963601

V0.2.2

HelloAgents V0.2.2 Release Notes

🎯 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! 🚀✨

Assets 2

09 Oct 06:24

jjyaoao

V0.2.1

91688c2

V0.2.1

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

Component	Packages	Description
MCP Protocol	`fastmcp>=2.0.0`	MCP server/client implementation (included in core)
A2A Protocol	`a2a-sdk` (optional)	Official A2A SDK for agent collaboration
ANP Protocol	Built-in	No external dependencies required

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

Transport	Use Case	Pros	Cons	Recommended
Memory	Unit testing, prototyping	Fastest, no network overhead	Same process only	⭐⭐⭐⭐⭐ (Testing)
Stdio	Local development, CLI tools	Simple, no network config	Local only, Windows compatibility	⭐⭐⭐⭐ (Development)
Command	Flexible local execution	Full control over process	Local only	⭐⭐⭐⭐ (Development)
HTTP	Production, remote services	Universal, firewall-friendly	No streaming, higher latency	⭐⭐⭐⭐⭐ (Production)
SSE	Real-time, streaming	Server push support	One-way, requires HTTP server	⭐⭐⭐ (Specific scenarios)

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

Server	Installation	Description
Filesystem	`npx -y @modelcontextprotocol/server-filesystem`	Local file operations
GitHub	`npx -y @modelcontextprotocol/server-github`	GitHub API integration
Slack	`npx -y @modelcontextprotocol/server-slack`	Slack messaging
Google Drive	`npx -y @modelcontextprotocol/server-gdrive`	Google Drive access
PostgreSQL	`npx -y @modelcontextprotocol/server-postgres`	Database operations
SQLite	`npx -y @modelcontextprotocol/server-sqlite`	SQLite database

🤝 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...

Assets 2

Releases: jjyaoao/HelloAgents

V1.0.0

HelloAgents V1.0.0 Release Notes

🎯 概述

✨ 核心亮点

🔧 安装与升级

新安装

从旧版本升级

验证安装

🆕 核心特性

阶段 1：基础设施

1. 工具响应协议（ToolResponse）

2. 上下文工程（Context Engineering）

阶段 2：核心能力

3. 可观测性（TraceLogger）

4. 熔断器（CircuitBreaker）

5. 会话持久化（SessionStore）

阶段 3：增强能力

6. 子代理机制（SubAgent）

7. Skills 知识外化

8. 乐观锁机制（Optimistic Locking）

9. TodoWrite 进度管理

阶段 4：辅助功能

10. DevLog 开发日志

11. 异步生命周期

阶段 5：核心架构重构

12. 流式输出与 SSE

13-14. Function Calling 统一架构

15. 日志系统（四种范式）

16. 自定义工具扩展

主要变更

向后兼容

📚 迁移指南

从 v0.x 迁移到 v1.0.0

🎉 致谢与展望

致谢

Uh oh!

V0.2.9

🎓 HelloAgents V0.2.9 - 学习版定稿公告

🎯 核心公告

📖 为什么需要学习版？

🚀 V0.2.9 核心特性

1. 核心框架

2. 工具系统

3. 记忆系统

4. RAG 系统

5. 协议支持

📦 安装指南

基础安装

完整安装

验证安装

🔮 下一步：Dev 开发版

📚 学习资源

官方教程

贡献指南

🙏 致谢

Uh oh!

V0.2.8

HelloAgents V0.2.8 Release Notes

🎯 Overview

✨ Core Features

🔧 Installation & Upgrade

New Installation

Upgrade from Previous Versions

Verify Installation

🆕 What's New

1. ToolAwareSimpleAgent - Tool Call Monitoring ✨

2. Custom Provider Support - Flexible LLM Integration 🌐

3. SearchTool File Reorganization 📁

🏗️ Architecture Improvements

Tool System Enhancements

LLM Provider System

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

Overview

Uh oh!

V0.2.7

Uh oh!

V0.2.6

Uh oh!

V0.2.5